npm - @steipete/oracle - Versions diffs - 0.16.1 → 0.17.0 - Mend

@steipete/oracle 0.16.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/README.md +72 -337
package/dist/bin/oracle-cli.js +184 -55
package/dist/docs-site/.nojekyll +0 -0
package/dist/docs-site/CNAME +1 -0
package/dist/docs-site/RELEASING.html +410 -0
package/dist/docs-site/agents.html +374 -0
package/dist/docs-site/anthropic.html +368 -0
package/dist/docs-site/bridge.html +416 -0
package/dist/docs-site/browser-mode.html +594 -0
package/dist/docs-site/chromium-forks.html +347 -0
package/dist/docs-site/cli-reference.html +346 -0
package/dist/docs-site/configuration.html +462 -0
package/dist/docs-site/favicon.svg +14 -0
package/dist/docs-site/followup.html +375 -0
package/dist/docs-site/gemini.html +383 -0
package/dist/docs-site/grok.html +325 -0
package/dist/docs-site/index.html +360 -0
package/dist/docs-site/install.html +335 -0
package/dist/docs-site/linux.html +321 -0
package/dist/docs-site/llms.txt +43 -0
package/dist/docs-site/manual-tests.html +596 -0
package/dist/docs-site/mcp.html +391 -0
package/dist/docs-site/multimodel.html +364 -0
package/dist/docs-site/mythical-pro-agents.html +360 -0
package/dist/docs-site/notifier.html +338 -0
package/dist/docs-site/openai-endpoints.html +410 -0
package/dist/docs-site/openrouter.html +344 -0
package/dist/docs-site/quickstart.html +369 -0
package/dist/docs-site/refactor/ux.html +532 -0
package/dist/docs-site/sessions.html +389 -0
package/dist/docs-site/social-card.png +0 -0
package/dist/docs-site/social-card.svg +79 -0
package/dist/docs-site/spec.html +363 -0
package/dist/docs-site/testing.html +320 -0
package/dist/docs-site/tui-debug.html +326 -0
package/dist/docs-site/windows-work.html +324 -0
package/dist/docs-site/windows.html +320 -0
package/dist/scripts/test-browser.js +1 -25
package/dist/src/browser/actions/modelSelection.js +36 -34
package/dist/src/browser/actions/navigation.js +8 -3
package/dist/src/browser/actions/thinkingTime.js +39 -3
package/dist/src/browser/chromeLifecycle.js +2 -37
package/dist/src/browser/index.js +23 -8
package/dist/src/browser/modelDisplay.js +67 -0
package/dist/src/browser/reattach.js +14 -1
package/dist/src/browser/recoverConversation.js +2 -1
package/dist/src/browser/sessionRunner.js +9 -10
package/dist/src/browser/wslHost.js +50 -0
package/dist/src/cli/browserConfig.js +31 -11
package/dist/src/cli/detach.js +21 -4
package/dist/src/cli/dryRun.js +13 -2
package/dist/src/cli/engine.js +2 -2
package/dist/src/cli/options.js +4 -0
package/dist/src/cli/sessionDisplay.js +60 -8
package/dist/src/cli/sessionLifecycle.js +2 -1
package/dist/src/cli/sessionRunner.js +110 -60
package/dist/src/cli/sessionTable.js +5 -1
package/dist/src/cli/tui/index.js +12 -4
package/dist/src/duration.js +3 -0
package/dist/src/gemini-web/client.js +19 -1
package/dist/src/oracle/modelResolver.js +8 -1
package/dist/src/oracle/request.js +9 -2
package/dist/src/oracle/run.js +43 -3
package/dist/src/sessionManager.js +41 -12
package/dist/vendor/oracle-notifier/OracleNotifier.app/Contents/CodeResources +0 -0
package/dist/vendor/oracle-notifier/OracleNotifier.app/Contents/MacOS/OracleNotifier +0 -0
package/package.json +15 -15
package/vendor/oracle-notifier/OracleNotifier.app/Contents/CodeResources +0 -0
package/vendor/oracle-notifier/OracleNotifier.app/Contents/MacOS/OracleNotifier +0 -0

package/dist/docs-site/browser-mode.html ADDED Viewed

@@ -0,0 +1,594 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Browser Mode — oracle</title>
+  <meta name="description" content="Browser Mode — oracle CLI documentation.">
+  <link rel="canonical" href="https://askoracle.sh/browser-mode.html">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="oracle">
+  <meta property="og:title" content="Browser Mode — oracle">
+  <meta property="og:description" content="Browser Mode — oracle CLI documentation.">
+  <meta property="og:url" content="https://askoracle.sh/browser-mode.html">
+  <meta property="og:image" content="https://askoracle.sh/social-card.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Browser Mode — oracle">
+  <meta name="twitter:description" content="Browser Mode — oracle CLI documentation.">
+  <meta name="twitter:image" content="https://askoracle.sh/social-card.png">
+  <link rel="icon" href="favicon.svg" type="image/svg+xml">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <script>(function(){var s;try{s=localStorage.getItem('theme')}catch(e){}var d=window.matchMedia&&matchMedia('(prefers-color-scheme: dark)').matches;document.documentElement.dataset.theme=s||(d?'dark':'light')})();</script>
+  <style>
+:root{
+  --ink:#0e0a1f;
+  --text:#1d1832;
+  --muted:#6b6582;
+  --subtle:#9c95b5;
+  --bg:#fafaff;
+  --paper:#ffffff;
+  --accent:#7c3aed;
+  --accent-soft:rgba(124,58,237,.10);
+  --accent-strong:#5b21b6;
+  --accent-2:#0ea5e9;
+  --accent-glow:#a78bfa;
+  --line:#e7e3f0;
+  --line-soft:#f2eff8;
+  --code-bg:#0c0a1a;
+  --code-fg:#e9e6f5;
+  --code-inline-fg:#1c1734;
+  --pill-border:#dcd5ec;
+  --shadow-card:0 4px 14px rgba(14,10,31,.08);
+  --scrollbar:#cbc4dc;
+}
+:root[data-theme="dark"]{
+  --ink:#f5f2ff;
+  --text:#cec7e4;
+  --muted:#9189a8;
+  --subtle:#6a6383;
+  --bg:#0a0815;
+  --paper:#15102a;
+  --accent:#a78bfa;
+  --accent-soft:rgba(167,139,250,.18);
+  --accent-strong:#c4b5fd;
+  --accent-2:#38bdf8;
+  --accent-glow:#c4b5fd;
+  --line:#272140;
+  --line-soft:#1c1734;
+  --code-bg:#06040d;
+  --code-fg:#e9e6f5;
+  --code-inline-fg:#e9e6f5;
+  --pill-border:#2c2549;
+  --shadow-card:0 4px 18px rgba(0,0,0,.45);
+  --scrollbar:#3a3358;
+}
+:root{color-scheme:light}
+:root[data-theme="dark"]{color-scheme:dark}
+*{box-sizing:border-box}
+html{scroll-behavior:smooth;scroll-padding-top:24px}
+body{margin:0;background:var(--bg);color:var(--text);font-family:"Inter",ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;line-height:1.65;overflow-x:hidden;-webkit-font-smoothing:antialiased;font-feature-settings:"cv02","cv03","cv04","cv11";transition:background-color .18s,color .18s}
+::selection{background:var(--accent);color:#fff}
+a{color:var(--accent);text-decoration:none;transition:color .12s}
+a:hover{text-decoration:underline;text-underline-offset:.2em}
+.shell{display:grid;grid-template-columns:268px minmax(0,1fr);min-height:100vh}
+.sidebar{position:sticky;top:0;height:100vh;overflow:auto;padding:24px 22px;background:var(--paper);border-right:1px solid var(--line);scrollbar-width:thin;scrollbar-color:var(--line) transparent;transition:background-color .18s,border-color .18s}
+.sidebar::-webkit-scrollbar{width:6px}
+.sidebar::-webkit-scrollbar-thumb{background:var(--line);border-radius:6px}
+.sidebar-head{display:flex;align-items:center;gap:10px;margin-bottom:24px}
+.brand{display:flex;align-items:center;gap:11px;color:var(--ink);text-decoration:none;flex:1;min-width:0}
+.brand:hover{text-decoration:none}
+.brand .mark{flex:0 0 30px;width:30px;height:30px;border-radius:50%;background:radial-gradient(circle at 32% 32%,#fff 0,#e0d4ff 22%,#7c3aed 60%,#1e1240 100%);box-shadow:0 0 0 1px rgba(124,58,237,.35),0 6px 18px rgba(124,58,237,.35);position:relative}
+.brand .mark::after{content:"";position:absolute;left:50%;top:50%;width:9px;height:9px;border-radius:50%;background:#0c0820;transform:translate(-50%,-50%)}
+.brand strong{display:block;font-size:1.05rem;line-height:1.1;font-weight:600;letter-spacing:0;color:var(--ink)}
+.brand small{display:block;color:var(--muted);font-size:.74rem;margin-top:3px;font-weight:400}
+.theme-toggle{display:inline-flex;align-items:center;justify-content:center;flex:0 0 auto;width:34px;height:34px;border-radius:8px;border:1px solid var(--line);background:var(--paper);color:var(--muted);cursor:pointer;padding:0;transition:border-color .15s,color .15s,background-color .15s,transform .12s}
+.theme-toggle:hover{border-color:var(--ink);color:var(--ink)}
+.theme-toggle:active{transform:scale(.94)}
+.theme-toggle svg{width:16px;height:16px;display:block}
+.theme-icon-sun{display:none}
+:root[data-theme="dark"] .theme-icon-sun{display:block}
+:root[data-theme="dark"] .theme-icon-moon{display:none}
+.search{display:block;margin:0 0 22px}
+.search span{display:block;color:var(--muted);font-size:.7rem;font-weight:600;text-transform:uppercase;letter-spacing:0;margin-bottom:7px}
+.search input{width:100%;border:1px solid var(--line);background:var(--paper);border-radius:8px;padding:9px 12px;font:inherit;font-size:.9rem;color:var(--text);outline:none;transition:border-color .15s,box-shadow .15s,background-color .18s}
+.search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft)}
+nav section{margin:0 0 18px}
+nav h2{font-size:.68rem;color:var(--muted);text-transform:uppercase;letter-spacing:0;margin:0 0 6px;font-weight:600}
+.nav-link{display:block;color:var(--text);text-decoration:none;border-radius:6px;padding:5px 10px;margin:1px 0;font-size:.9rem;line-height:1.4;transition:background .12s,color .12s}
+.nav-link:hover{background:var(--line-soft);color:var(--ink);text-decoration:none}
+.nav-link.active{background:var(--accent-soft);color:var(--accent);font-weight:600}
+main{min-width:0;padding:32px clamp(20px,4.5vw,56px) 80px;max-width:1180px;margin:0 auto;width:100%}
+.hero{display:flex;align-items:flex-end;justify-content:space-between;gap:22px;border-bottom:1px solid var(--line);padding:8px 0 22px;margin-bottom:8px;flex-wrap:wrap}
+.hero-text{min-width:0;flex:1 1 320px}
+.eyebrow{margin:0 0 8px;color:var(--muted);font-weight:600;text-transform:uppercase;letter-spacing:0;font-size:.7rem}
+.hero h1{font-size:2.25rem;line-height:1.1;letter-spacing:0;margin:0;font-weight:700;color:var(--ink)}
+.hero-meta{display:flex;gap:8px;flex:0 0 auto;flex-wrap:wrap}
+.repo,.edit,.btn-ghost{border:1px solid var(--line);color:var(--text);text-decoration:none;border-radius:7px;padding:6px 11px;font-weight:500;font-size:.83rem;background:var(--paper);transition:border-color .15s,color .15s,background .15s}
+.repo:hover,.edit:hover,.btn-ghost:hover{border-color:var(--ink);color:var(--ink);text-decoration:none}
+.edit{color:var(--muted)}
+.home-hero{position:relative;padding:24px 0 32px;margin-bottom:8px;border-bottom:1px solid var(--line)}
+.home-hero>*{position:relative;z-index:1}
+.home-hero h1{font-size:3.4rem;line-height:1.04;letter-spacing:0;margin:0 0 .35em;font-weight:700;color:var(--ink);background:linear-gradient(135deg,var(--ink) 0,#7c3aed 60%,#0ea5e9 100%);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}
+:root[data-theme="dark"] .home-hero h1{background:linear-gradient(135deg,#f5f2ff 0,#c4b5fd 50%,#7dd3fc 100%);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}
+.home-hero .lede{font-size:1.18rem;line-height:1.55;color:var(--text);margin:0 0 1.2em;max-width:62ch}
+.home-cta{display:flex;flex-wrap:wrap;gap:10px;align-items:center;margin:0 0 18px}
+.home-cta .btn{display:inline-flex;align-items:center;gap:7px;border-radius:8px;padding:10px 16px;font-weight:600;font-size:.92rem;text-decoration:none;transition:background .15s,border-color .15s,color .15s,transform .12s}
+.home-cta .btn-primary{background:linear-gradient(135deg,var(--accent),var(--accent-strong));color:#fff;border:1px solid var(--accent);box-shadow:0 4px 14px rgba(124,58,237,.35)}
+.home-cta .btn-primary:hover{background:var(--accent-strong);border-color:var(--accent-strong);text-decoration:none;transform:translateY(-1px)}
+.home-cta .btn-ghost{padding:10px 16px}
+.home-install{display:flex;align-items:center;gap:12px;background:var(--code-bg);color:var(--code-fg);border-radius:8px;padding:10px 10px 10px 16px;font:500 .9rem/1.2 "JetBrains Mono","SF Mono",ui-monospace,monospace;max-width:34em;border:1px solid #1f1840}
+.home-install .prompt{color:#6f63a3;user-select:none;flex:0 0 auto}
+.home-install code{flex:1;background:transparent;border:0;color:var(--code-fg);font:inherit;padding:0;white-space:pre;overflow:hidden;text-overflow:ellipsis}
+.home-install .copy{flex:0 0 auto;background:rgba(255,255,255,.08);color:var(--code-fg);border:1px solid rgba(255,255,255,.16);border-radius:6px;padding:5px 11px;font:500 .72rem/1 "Inter",sans-serif;cursor:pointer;transition:background .15s,border-color .15s}
+.home-install .copy:hover{background:rgba(255,255,255,.16)}
+.home-install .copy.copied{background:var(--accent);border-color:var(--accent)}
+.home-services{display:flex;flex-wrap:wrap;gap:6px;margin:6px 0 18px}
+.home-services span{display:inline-block;padding:3px 10px;border:1px solid var(--pill-border);border-radius:999px;font-size:.78rem;color:var(--muted);background:var(--paper)}
+.home-services span.pill-pro{background:var(--accent-soft);color:var(--accent);border-color:transparent;font-weight:600}
+.home-visual{display:block;width:min(100%,620px);height:auto;margin:22px 0 0;border-radius:8px;border:1px solid var(--line);box-shadow:var(--shadow-card);background:var(--paper)}
+.doc-grid{display:grid;grid-template-columns:minmax(0,1fr);gap:48px;margin-top:24px}
+.doc-grid-home{margin-top:8px}
+@media(min-width:1180px){.doc-grid{grid-template-columns:minmax(0,72ch) 200px;justify-content:start}.doc-grid-home{grid-template-columns:minmax(0,76ch);justify-content:start}}
+.doc{min-width:0;max-width:72ch;overflow-wrap:break-word}
+.doc-home{max-width:76ch}
+.doc h1{font-size:2.6rem;line-height:1.08;letter-spacing:0;margin:0 0 .4em;font-weight:700;color:var(--ink)}
+body:not(.home) .doc>h1:first-child{display:none}
+.doc h2{font-size:1.45rem;line-height:1.2;margin:2em 0 .5em;font-weight:600;letter-spacing:0;color:var(--ink);position:relative}
+.doc h3{font-size:1.1rem;margin:1.7em 0 .35em;position:relative;font-weight:600;color:var(--ink);letter-spacing:0}
+.doc h4{font-size:.98rem;margin:1.4em 0 .25em;color:var(--ink);position:relative;font-weight:600}
+.doc h2:first-child,.doc h3:first-child,.doc h4:first-child{margin-top:.2em}
+.doc :is(h2,h3,h4) .anchor{position:absolute;left:-1.05em;top:0;color:var(--subtle);opacity:0;text-decoration:none;font-weight:400;padding-right:.3em;transition:opacity .12s,color .12s}
+.doc :is(h2,h3,h4):hover .anchor{opacity:.7}
+.doc :is(h2,h3,h4) .anchor:hover{opacity:1;color:var(--accent);text-decoration:none}
+.doc p{margin:0 0 1.05em}
+.doc ul,.doc ol{padding-left:1.3rem;margin:0 0 1.15em}
+.doc li{margin:.25em 0}
+.doc li>p{margin:0 0 .4em}
+.doc strong{font-weight:600;color:var(--ink)}
+.doc em{font-style:italic}
+.doc code{font-family:"JetBrains Mono","SF Mono",ui-monospace,monospace;font-size:.84em;background:var(--line-soft);border:1px solid var(--line);border-radius:5px;padding:.08em .35em;color:var(--code-inline-fg)}
+.doc pre{position:relative;overflow:auto;background:var(--code-bg);color:var(--code-fg);border-radius:8px;padding:14px 18px;margin:1.3em 0;font-size:.85em;line-height:1.6;scrollbar-width:thin;scrollbar-color:#3a3358 transparent;border:1px solid #221c40}
+.doc pre.shiki{background:var(--code-bg)!important;color:var(--code-fg)!important}
+.doc pre::-webkit-scrollbar{height:8px;width:8px}
+.doc pre::-webkit-scrollbar-thumb{background:#3a3358;border-radius:8px}
+.doc pre code{display:block;background:transparent;border:0;color:inherit;padding:0;font-size:1em;white-space:pre}
+.doc pre code .line{display:block;min-height:1.6em}
+.doc pre .copy{position:absolute;top:8px;right:8px;background:rgba(255,255,255,.06);color:var(--code-fg);border:1px solid rgba(255,255,255,.16);border-radius:6px;padding:3px 9px;font:500 .7rem/1 "Inter",sans-serif;cursor:pointer;opacity:0;transition:opacity .15s,background .15s,border-color .15s}
+.doc pre:hover .copy,.doc pre .copy:focus{opacity:1}
+.doc pre .copy:hover{background:rgba(255,255,255,.12)}
+.doc pre .copy.copied{background:var(--accent);border-color:var(--accent);opacity:1}
+.doc blockquote{margin:1.4em 0;padding:10px 16px;border-left:3px solid var(--accent);background:var(--accent-soft);border-radius:0 8px 8px 0;color:var(--text)}
+.doc blockquote p:last-child{margin-bottom:0}
+.doc table{width:100%;border-collapse:collapse;margin:1.2em 0;font-size:.92em}
+.doc th,.doc td{border-bottom:1px solid var(--line);padding:9px 10px;text-align:left;vertical-align:top}
+.doc th{font-weight:600;color:var(--ink);background:var(--line-soft);border-bottom:1px solid var(--line)}
+.doc hr{border:0;border-top:1px solid var(--line);margin:2.2em 0}
+.toc{position:sticky;top:24px;align-self:start;font-size:.84rem;padding-left:14px;border-left:1px solid var(--line);max-height:calc(100vh - 48px);overflow:auto;scrollbar-width:thin;scrollbar-color:var(--line) transparent}
+.toc::-webkit-scrollbar{width:5px}
+.toc::-webkit-scrollbar-thumb{background:var(--line);border-radius:5px}
+.toc h2{font-size:.66rem;color:var(--muted);text-transform:uppercase;letter-spacing:0;margin:0 0 10px;font-weight:600}
+.toc a{display:block;color:var(--muted);text-decoration:none;padding:4px 0 4px 10px;line-height:1.35;border-left:2px solid transparent;margin-left:-12px;transition:color .12s,border-color .12s}
+.toc a:hover{color:var(--ink);text-decoration:none}
+.toc a.active{color:var(--accent);border-left-color:var(--accent);font-weight:500}
+.toc-l3{padding-left:22px!important;font-size:.94em}
+@media(max-width:1179px){.toc{display:none}}
+.page-nav{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:48px;border-top:1px solid var(--line);padding-top:20px}
+.page-nav>a{display:block;border:1px solid var(--line);background:var(--paper);border-radius:9px;padding:13px 16px;text-decoration:none;color:var(--text);transition:border-color .15s,transform .15s,box-shadow .15s,background-color .18s}
+.page-nav>a:hover{border-color:var(--accent);text-decoration:none;color:var(--ink)}
+.page-nav small{display:block;color:var(--muted);font-size:.7rem;text-transform:uppercase;letter-spacing:0;margin-bottom:5px;font-weight:600}
+.page-nav span{display:block;font-weight:600;line-height:1.3;color:var(--ink)}
+.page-nav-prev{text-align:left}
+.page-nav-next{text-align:right;grid-column:2}
+.page-nav-prev:only-child{grid-column:1}
+.nav-toggle{display:none;position:fixed;top:14px;right:14px;top:calc(14px + env(safe-area-inset-top, 0px));right:calc(14px + env(safe-area-inset-right, 0px));z-index:20;width:40px;height:40px;border-radius:9px;background:var(--paper);border:1px solid var(--line);color:var(--ink);cursor:pointer;padding:10px 9px;flex-direction:column;align-items:stretch;justify-content:space-between;box-shadow:var(--shadow-card)}
+.nav-toggle span{display:block;width:100%;height:2px;flex:0 0 2px;background:currentColor;border-radius:2px;transition:transform .2s,opacity .2s}
+.nav-toggle[aria-expanded="true"] span:nth-child(1){transform:translateY(8px) rotate(45deg)}
+.nav-toggle[aria-expanded="true"] span:nth-child(2){opacity:0}
+.nav-toggle[aria-expanded="true"] span:nth-child(3){transform:translateY(-8px) rotate(-45deg)}
+@media(max-width:900px){
+  .shell{display:block}
+  .sidebar{position:fixed;inset:0 30% 0 0;max-width:320px;height:100vh;z-index:15;transform:translateX(-100%);transition:transform .25s ease,background-color .18s,border-color .18s;box-shadow:0 18px 40px rgba(0,0,0,.18);background:var(--paper);pointer-events:none}
+  .sidebar.open{transform:translateX(0);pointer-events:auto}
+  .nav-toggle{display:flex}
+  main{padding:64px 18px 56px}
+  .hero{padding-top:6px}
+  .hero h1{font-size:1.8rem}
+  .home-hero h1{font-size:2.45rem}
+  .doc h1{font-size:2.1rem}
+  .hero-meta{width:100%;justify-content:flex-start}
+  .home-hero{padding-top:8px}
+  .home-visual{margin-top:18px}
+  .doc{padding:0}
+  .doc-grid{margin-top:18px;gap:24px}
+  .doc :is(h2,h3,h4) .anchor{display:none}
+}
+@media(max-width:520px){
+  main{padding:60px 14px 48px}
+  .doc pre{margin-left:-14px;margin-right:-14px;border-radius:0;border-left:0;border-right:0}
+  .home-install{flex-wrap:wrap}
+}
+</style>
+</head>
+<body>
+  <button class="nav-toggle" type="button" aria-label="Toggle navigation" aria-expanded="false">
+    <span aria-hidden="true"></span><span aria-hidden="true"></span><span aria-hidden="true"></span>
+  </button>
+  <div class="shell">
+    <aside class="sidebar">
+      <div class="sidebar-head">
+        <a class="brand" href="./" aria-label="oracle docs home">
+          <span class="mark" aria-hidden="true"></span>
+          <span><strong>oracle</strong><small>askoracle.sh</small></span>
+        </a>
+        <button class="theme-toggle" type="button" aria-label="Toggle dark mode" aria-pressed="false" data-theme-toggle>
+    <svg class="theme-icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
+    <svg class="theme-icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
+  </button>
+      </div>
+      <label class="search"><span>Search</span><input id="doc-search" type="search" placeholder="browser, mcp, sessions"></label>
+      <nav><section><h2>Start</h2><a class="nav-link" href="./">Overview</a><a class="nav-link" href="install.html">Install</a><a class="nav-link" href="quickstart.html">Quickstart</a><a class="nav-link" href="configuration.html">Local configuration (JSON5)</a></section><section><h2>Mythical Pro Agents</h2><a class="nav-link" href="mythical-pro-agents.html">Mythical Pro Agents</a><a class="nav-link" href="openai-endpoints.html">OpenAI-Compatible Endpoints</a><a class="nav-link" href="anthropic.html">Anthropic (Claude) Integration Plan</a><a class="nav-link" href="gemini.html">Gemini Integration</a><a class="nav-link" href="openrouter.html">OpenRouter</a><a class="nav-link" href="grok.html">Grok 4.1 (xAI) Support</a></section><section><h2>Browser Mode</h2><a class="nav-link active" href="browser-mode.html">Browser Mode</a><a class="nav-link" href="chromium-forks.html">Chromium-based browsers (Chromium, Edge, Brave variants)</a><a class="nav-link" href="linux.html">Linux Notes</a><a class="nav-link" href="windows.html">Windows compatibility notes</a><a class="nav-link" href="windows-work.html">Windows Work</a><a class="nav-link" href="bridge.html">Bridge (Windows-hosted ChatGPT session → Linux clients)</a></section><section><h2>Agents &amp; MCP</h2><a class="nav-link" href="agents.html">Coding Agents</a><a class="nav-link" href="mcp.html">MCP Server</a></section><section><h2>Workflows</h2><a class="nav-link" href="sessions.html">Sessions</a><a class="nav-link" href="followup.html">Followups &amp; Lineage</a><a class="nav-link" href="multimodel.html">Multi-Model Execution</a></section><section><h2>Reference</h2><a class="nav-link" href="cli-reference.html">CLI Reference</a><a class="nav-link" href="spec.html">Spec</a><a class="nav-link" href="notifier.html">Session completion notifications</a><a class="nav-link" href="tui-debug.html">TUI navigation crash notes (2025-11-19)</a><a class="nav-link" href="manual-tests.html">Manual Test Suite (Browser Mode + Live API)</a><a class="nav-link" href="testing.html">Testing quickstart</a><a class="nav-link" href="RELEASING.html">Release Checklist (npm + Homebrew)</a></section></nav>
+    </aside>
+    <main>
+      <header class="hero">
+        <div class="hero-text">
+          <p class="eyebrow">Browser Mode</p>
+          <h1>Browser Mode</h1>
+        </div>
+        <div class="hero-meta">
+          <a class="repo" href="https://github.com/steipete/oracle" rel="noopener">GitHub</a>
+          <a class="edit" href="https://github.com/steipete/oracle/edit/main/docs/browser-mode.md" rel="noopener">Edit page</a>
+        </div>
+      </header>
+      <div class="doc-grid">
+        <article class="doc"><h1 id="browser-mode">Browser Mode</h1>
+<p>Oracle’s <code>--engine browser</code> supports three different execution paths:</p>
+<ul>
+<li><strong>ChatGPT launcher mode</strong> (GPT-\* models): Oracle launches Chrome itself and drives the ChatGPT web UI over CDP.</li>
+<li><strong>ChatGPT attach-running mode</strong> (GPT-\* models): Oracle attaches to your already-running local Chrome session through Chrome’s local remote-debugging toggle, opens a dedicated tab, and leaves the browser process/profile alone.</li>
+<li><strong>Gemini web mode</strong> (Gemini models): talks directly to <code>gemini.google.com</code> using your signed-in Chrome cookies (no ChatGPT automation).</li>
+</ul>
+<p>If you’re running Gemini, also see <code>docs/gemini.md</code>.</p>
+<p><code>oracle --engine browser</code> routes the assembled prompt bundle through the ChatGPT web UI instead of the Responses API. (Legacy <code>--browser</code> still maps to <code>--engine browser</code>, but it will be removed.) If you omit <code>--engine</code>, Oracle first honors <code>ORACLE_ENGINE</code>, then any <code>engine</code> value in the effective config, including project <code>.oracle/config.json</code> files layered over <code>~/.oracle/config.json</code>. It auto-picks API when <code>OPENAI_API_KEY</code> is available and falls back to browser otherwise. The CLI writes the same session metadata/logs as API runs, and by default pastes the payload into ChatGPT via a temporary Chrome profile (manual-login mode can reuse a persistent automation profile).</p>
+<p><code>--preview</code> now works with <code>--engine browser</code>: it renders the composed prompt, lists which files would be uploaded vs inlined, and shows the bundle location when bundling is enabled, without launching Chrome.</p>
+<h2 id="quick-example-browser-mode-with-custom-cookies"><a class="anchor" href="#quick-example-browser-mode-with-custom-cookies" aria-label="Anchor link">#</a>Quick example: browser mode with custom cookies</h2>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#768390"># Minimal inline-cookies flow: keep ChatGPT logged in without Keychain</span></span>
+<span class="line"><span style="color:#F69D50">jq</span><span style="color:#96D0FF"> '.'</span><span style="color:#96D0FF"> ~/.oracle/cookies.json</span><span style="color:#768390">  # file must contain CookieParam[]</span></span>
+<span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-inline-cookies-file</span><span style="color:#96D0FF"> ~/.oracle/cookies.json</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --model</span><span style="color:#96D0FF"> "GPT-5.5 Pro"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Run the UI smoke"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> "src/**/*.ts"</span><span style="color:#6CB6FF"> --file</span><span style="color:#96D0FF"> "!src/**/*.test.ts"</span></span></code></pre>
+<p><code>~/.oracle/cookies.json</code> should be a JSON array shaped like:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-json"><span class="line"><span style="color:#ADBAC7">[</span></span>
+<span class="line"><span style="color:#ADBAC7">  {</span></span>
+<span class="line"><span style="color:#8DDB8C">    "name"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"__Secure-next-auth.session-token"</span><span style="color:#ADBAC7">,</span></span>
+<span class="line"><span style="color:#8DDB8C">    "value"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"&#x3C;token>"</span><span style="color:#ADBAC7">,</span></span>
+<span class="line"><span style="color:#8DDB8C">    "domain"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"chatgpt.com"</span><span style="color:#ADBAC7">,</span></span>
+<span class="line"><span style="color:#8DDB8C">    "path"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"/"</span><span style="color:#ADBAC7">,</span></span>
+<span class="line"><span style="color:#8DDB8C">    "secure"</span><span style="color:#ADBAC7">: </span><span style="color:#6CB6FF">true</span><span style="color:#ADBAC7">,</span></span>
+<span class="line"><span style="color:#8DDB8C">    "httpOnly"</span><span style="color:#ADBAC7">: </span><span style="color:#6CB6FF">true</span></span>
+<span class="line"><span style="color:#ADBAC7">  },</span></span>
+<span class="line"><span style="color:#ADBAC7">  { </span><span style="color:#8DDB8C">"name"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"_account"</span><span style="color:#ADBAC7">, </span><span style="color:#8DDB8C">"value"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"personal"</span><span style="color:#ADBAC7">, </span><span style="color:#8DDB8C">"domain"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"chatgpt.com"</span><span style="color:#ADBAC7">, </span><span style="color:#8DDB8C">"path"</span><span style="color:#ADBAC7">: </span><span style="color:#96D0FF">"/"</span><span style="color:#ADBAC7">, </span><span style="color:#8DDB8C">"secure"</span><span style="color:#ADBAC7">: </span><span style="color:#6CB6FF">true</span><span style="color:#ADBAC7"> }</span></span>
+<span class="line"><span style="color:#ADBAC7">]</span></span></code></pre>
+<p>You can pass the same payload inline (<code>--browser-inline-cookies &#39;&lt;json or base64&gt;&#39;</code>) or via env (<code>ORACLE_BROWSER_COOKIES_JSON</code>, <code>ORACLE_BROWSER_COOKIES_FILE</code>). Cloudflare cookies (<code>cf_clearance</code>, <code>__cf_bm</code>, etc.) are only needed when you hit a challenge.</p>
+<h2 id="quick-example-attach-to-your-running-chrome"><a class="anchor" href="#quick-example-attach-to-your-running-chrome" aria-label="Anchor link">#</a>Quick example: attach to your running Chrome</h2>
+<p>Use this when you already have a signed-in Chrome session running with DevTools access enabled and want Oracle to reuse that browser instead of launching its own copy.</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-attach-running</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --model</span><span style="color:#96D0FF"> "GPT-5.5 Pro"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Summarize the last assistant response in one paragraph"</span></span></code></pre>
+<p>Notes:</p>
+<ul>
+<li><code>--browser-attach-running</code> defaults to local attach discovery at <code>127.0.0.1:9222</code>.</li>
+<li>If the browser UI shows a different local endpoint, you can point Oracle at it explicitly:</li>
+<p>``<code>bash oracle --engine browser \ --browser-attach-running \ --remote-chrome 127.0.0.1:63332 \ --model &quot;GPT-5.5 Pro&quot; \ -p &quot;Summarize the last assistant response in one paragraph&quot; </code>``</p>
+<li>Oracle reads local <code>DevToolsActivePort</code> metadata, connects to the browser websocket directly, and then reuses the normal CDP automation flow.</li>
+<li>If Chrome shows a remote-debugging approval prompt on first attach, Oracle issues one attach request and waits briefly for you to allow it before failing.</li>
+<li>Attach mode always opens a fresh Oracle-owned tab and closes only that tab after a successful run.</li>
+<li>Cookie sync, Chrome launch flags, and profile lifecycle flags are skipped because the browser is already running.</li>
+<li>If Chrome is not exposing a classic <code>/json/version</code> endpoint, use <code>--browser-attach-running</code> instead of standalone <code>--remote-chrome</code>.</li>
+</ul>
+<h2 id="current-pipeline"><a class="anchor" href="#current-pipeline" aria-label="Anchor link">#</a>Current Pipeline</h2>
+<ol>
+<li><strong>Prompt assembly</strong> – we reuse the normal prompt builder (<code>buildPrompt</code>) and the markdown renderer. Browser mode pastes the system + user text (no special markers) into the ChatGPT composer and, by default, pastes resolved file contents inline until the total pasted content reaches ~60k characters (then switches to uploads).</li>
+<li><strong>Automation stack</strong> – code lives under <code>src/browser/</code>:</li>
+</ol>
+<ul>
+<li>Launcher mode starts Chrome via <code>chrome-launcher</code> and connects with <code>chrome-remote-interface</code>.</li>
+<li>Attach-running mode reads local <code>DevToolsActivePort</code> metadata for the selected local port, connects to the browser websocket, opens a dedicated tab, and reuses the same DOM automation/capture flow against that attached browser.</li>
+<li>Launcher mode can optionally copy cookies from the requested browser profile via Oracle’s built-in cookie reader (Keychain/DPAPI aware) so you stay signed in.</li>
+<li>Navigates to <code>chatgpt.com</code>, switches the model to the requested GPT-5.5 / GPT-5.4 / GPT-5.2 variant, optionally activates Deep Research, pastes the prompt, waits for completion, and copies the markdown via the built-in “copy turn” button.</li>
+<li>Immediately probes the cookie-authenticated <code>/api/auth/session</code> endpoint in the ChatGPT tab and checks only whether it contains a user; returned tokens are never logged. If that endpoint is unavailable, Oracle falls back to the legacy <code>/backend-api/me</code> probe and a visible composer plus profile or chat-history authentication signals. Auth pages, visible login controls, resolved sessions without a user, composer-only shells, and pages without profile/history signals still fail with login guidance.</li>
+<li>When <code>--file</code> inputs would push the pasted composer content over ~60k characters, we switch to uploading attachments (optionally bundled) and wait for ChatGPT to re-enable the send button before submitting the combined system+user prompt.</li>
+<li>Launcher mode cleans up the temporary profile unless <code>--browser-keep-browser</code> is passed.</li>
+</ul>
+<ol>
+<li><strong>Session integration</strong> – browser sessions use the normal log writer, add <code>mode: &quot;browser&quot;</code> plus <code>browser.config/runtime</code> metadata, and persist Chrome pid/port or websocket attach metadata plus the Oracle-owned target/tab URL for reattach.</li>
+<li><strong>Usage accounting</strong> – we estimate input tokens with the same tokenizer used for API runs and estimate output tokens via <code>estimateTokenCount</code>. <code>oracle status</code> therefore shows comparable cost/timing info even though the call ran through the browser.</li>
+</ol>
+<h3 id="cli-options"><a class="anchor" href="#cli-options" aria-label="Anchor link">#</a>CLI Options</h3>
+<ul>
+<li><code>--engine browser</code>: enables browser mode (legacy <code>--browser</code> remains as an alias for now). Without <code>--engine</code>, Oracle chooses API when <code>OPENAI_API_KEY</code> exists, otherwise browser.</li>
+<li><code>--browser-chrome-profile</code>, <code>--browser-chrome-path</code>: cookie source + binary override (defaults to the standard <code>&quot;Default&quot;</code> Chrome profile so existing ChatGPT logins carry over).</li>
+<li><code>--browser-cookie-path</code>: explicit path to the Chrome/Chromium/Edge <code>Cookies</code> SQLite DB. Handy when you launch a fork via <code>--browser-chrome-path</code> and want to copy its session cookies; see <a href="chromium-forks.html">docs/chromium-forks.md</a> for examples.</li>
+<li><code>--browser-attach-running</code>: attach to a local already-running browser instead of launching Chrome directly. Defaults to <code>127.0.0.1:9222</code>; combine with <code>--remote-chrome &lt;host:port&gt;</code> to use a different local attach hint.</li>
+<li><code>--chatgpt-url</code>: override the ChatGPT base URL. Works with the root homepage (<code>https://chatgpt.com/</code>), Temporary Chat (<code>https://chatgpt.com/?temporary-chat=true</code>), <strong>or</strong> a specific workspace/folder link such as <code>https://chatgpt.com/g/.../project</code>. <code>--browser-url</code> stays as a hidden alias.</li>
+<li><code>--browser-timeout</code>, <code>--browser-input-timeout</code>, <code>--browser-attachment-timeout</code>: <code>1200s (20m)</code>/<code>60s</code>/<code>45s</code> defaults. The attachment timeout controls upload/readiness before clicking Send and can also be set with <code>ORACLE_BROWSER_ATTACHMENT_TIMEOUT</code> or <code>browser.attachmentTimeoutMs</code>. Durations accept <code>ms</code>, <code>s</code>, <code>m</code>, or <code>h</code> and can be chained (<code>1h2m10s</code>).</li>
+<li><code>--browser-recheck-delay</code>, <code>--browser-recheck-timeout</code>: after an assistant timeout, wait the delay, revisit the conversation, and retry capture (default recheck timeout 120s). Useful for Pro runs that finish later.</li>
+<li><code>--browser-reuse-wait</code>: wait for a shared Chrome profile (DevToolsActivePort) to appear before launching a new Chrome. Helps multiple parallel runs reuse the same Chromium instance.</li>
+<li><code>--browser-profile-lock-timeout</code>: wait for the shared manual-login profile lock before sending, serializing parallel runs that share a Chrome profile.</li>
+<li><code>--browser-max-concurrent-tabs</code>: soft limit for simultaneous ChatGPT tabs sharing one manual-login profile (default <code>3</code>). Set <code>ORACLE_BROWSER_MAX_CONCURRENT_TABS</code> for a per-host default; explicit CLI/config values win. Additional runs wait up to the browser timeout for a slot and log <code>[browser] Waiting for ChatGPT browser slot...</code>.</li>
+<li><code>--browser-auto-reattach-delay</code>, <code>--browser-auto-reattach-interval</code>, <code>--browser-auto-reattach-timeout</code>: after a timeout, start periodic auto-reattach attempts (delay before first attempt, repeat interval, per-attempt timeout). This lets Oracle keep polling a finished Pro response without manual <code>oracle session</code> runs.</li>
+<li><code>--heartbeat</code>: browser mode uses this interval to emit long-run ChatGPT status. When ChatGPT exposes a Thinking/Reasoning disclosure, Oracle opens it and logs only liveness metadata such as sidecar presence, UI progress percentage, elapsed time, and last-change age. It does not log the reasoning text.</li>
+<li>If an assistant response still times out (common with long Pro runs), Oracle marks the session as an incomplete capture, stores reattach/runtime diagnostics, and keeps enough browser metadata for <code>oracle session &lt;id&gt;</code> to recover the final answer. Visible ChatGPT rate-limit, temporary-unavailable, and authentication/challenge warnings are included in the error and session metadata instead of being reduced to a generic timeout. Increase <code>--browser-timeout</code> only when the browser session is truly unrecoverable.</li>
+<li><code>--browser-model-strategy &lt;select|current|ignore&gt;</code>: control ChatGPT model selection. <code>select</code> (default) switches to the requested model; <code>current</code> keeps the active model and logs its label; <code>ignore</code> skips the picker entirely. (Ignored for Gemini web runs.)</li>
+<li>Temporary Chat can reduce account-sidebar clutter for one-shot browser consults, but it is a different ChatGPT workflow: Oracle skips archive attempts there and the local transcript/artifacts are the durable record. Verify live behavior before relying on Project Sources, Deep Research reports, or multi-turn persistence.</li>
+<li><code>--browser-thinking-time &lt;light|standard|extended|heavy&gt;</code>: set the ChatGPT thinking-time intensity (Thinking/Pro models only). You can also set a default in <code>~/.oracle/config.json</code> via <code>browser.thinkingTime</code>.</li>
+<li>GPT-5.5 Pro Extended is verified from the selected item in ChatGPT&#39;s standalone Pro/Thinking effort pill or compatible Intelligence/model-picker menu. A run <strong>fails closed</strong> if Extended cannot be confirmed rather than silently submitting at a weaker effort. Detection failures write a bounded, redacted model-picker diagnostic to the normal session log.</li>
+<li><code>--browser-research deep</code>: activate ChatGPT Deep Research before submitting the prompt. Use this for broad public-web research and final cited reports, not as a replacement for GPT-5.x Pro Heavy code review or pure reasoning.</li>
+<li><code>--browser-follow-up &lt;prompt&gt;</code>: submit another prompt in the same ChatGPT conversation after the initial answer. Repeat the flag for multi-turn reviews such as “challenge your recommendation”, “compare against this constraint”, then “give the final decision”. Deep Research has its own report lifecycle, so browser follow-ups are rejected when <code>--browser-research deep</code> is enabled.</li>
+<li><code>--followup &lt;session-id&gt;</code>: reopen the exact saved ChatGPT conversation from a completed browser session. Oracle inherits the parent browser profile, configuration, and model, then verifies the thread and prior turns before submitting.</li>
+<li><code>--browser-archive &lt;auto|always|never&gt;</code>: archive completed ChatGPT conversations after local artifacts are saved. The default <code>auto</code> archives only successful one-shot chats and skips project, Deep Research, multi-turn, failed, and incomplete sessions.</li>
+<li><code>--browser-port &lt;port&gt;</code> (alias: <code>--browser-debug-port</code>; env: <code>ORACLE_BROWSER_PORT</code>/<code>ORACLE_BROWSER_DEBUG_PORT</code>): pin the DevTools port (handy on WSL/Windows firewalls). When omitted, a random open port is chosen.</li>
+<li><code>ORACLE_CHATGPT_ACCOUNT_EMAIL</code>: exact saved-account email to select if ChatGPT shows its “Welcome back” account picker. Set it on the machine running browser automation. Oracle never logs the address; without it, Oracle selects only a single unambiguous saved account and fails closed when several are present.</li>
+<li><code>--browser-no-cookie-sync</code>, <code>--browser-manual-login</code> (persistent automation profile + user-driven login), <code>--browser-headless</code>, <code>--browser-hide-window</code>, <code>--browser-keep-browser</code>, and the global <code>-v/--verbose</code> flag for detailed automation logs.</li>
+<li><code>--copy-profile &lt;dir&gt;</code>: copy a signed-in Chrome user-data directory (e.g. <code>&quot;$HOME/Library/Application Support/Google/Chrome&quot;</code>) to a throwaway profile and run against it, reusing your live ChatGPT session with no manual sign-in. Oracle copies the profile recorded as active in <code>Local State</code>; pass <code>--browser-chrome-profile &lt;name&gt;</code> to select another direct child profile. The copy is launched with the real Keychain (not mocked) so its encrypted cookies decrypt, and is always deleted afterward—including setup/launch failures, incomplete captures, Cloudflare challenges, and interrupts. Copied-profile runs cannot be kept or reattached. Not compatible with <code>--browser-keep-browser</code>, <code>--browser-manual-login</code>, <code>--browser-attach-running</code>, <code>--remote-chrome</code>, or <code>--remote-host</code>, and fails fast if the required <code>Local State</code> cannot be copied. macOS/Linux; requires <code>rsync</code>.</li>
+<li><code>--browser-url</code>: override ChatGPT base URL if needed.</li>
+<li><code>--browser-attachments &lt;auto|never|always&gt;</code>: control how <code>--file</code> inputs are delivered in browser mode. Default <code>auto</code> pastes text contents inline up to ~60k characters and uploads larger or raw files. <code>never</code> requires inline-compatible text inputs and rejects raw/binary files.</li>
+<li><code>--browser-inline-files</code>: alias for <code>--browser-attachments never</code> (forces inline paste; never uploads attachments).</li>
+<li><code>--browser-bundle-files</code>: bundle all resolved attachments into a single temp file before uploading (only used when uploads are enabled/selected).</li>
+<li><code>--browser-bundle-format &lt;auto|text|zip&gt;</code>: choose the bundle format. <code>auto</code> uses a text bundle for text-only inputs and a byte-preserving ZIP when bundled inputs include raw files; <code>text</code> keeps the single Markdown-style text bundle; <code>zip</code> archives the original file bytes. ZIP bundle inputs are capped at 128 MiB because bundle creation is in-memory.</li>
+<li>sqlite bindings: automatic rebuilds now require <code>ORACLE_ALLOW_SQLITE_REBUILD=1</code>. Without it, the CLI logs instructions instead of running <code>pnpm rebuild</code> on your behalf.</li>
+<li><code>--model</code>: the same GPT-5.6 aliases work in API and browser mode. Use <code>gpt-5.6</code> for the current GPT-5.6 default or <code>gpt-5.6-sol</code> to pin Sol; browser mode maps either alias to the <code>GPT-5.6 Sol</code> picker entry, while API mode sends the corresponding first-party OpenAI model ID. GPT-5.2 base, Instant, and Thinking aliases remain available through the API but browser mode rejects them because ChatGPT retired those picker entries. Legacy Pro aliases still resolve to the latest Pro picker target.</li>
+<li>Cookie sync is mandatory—if we can’t copy cookies from Chrome, the run exits early. By default Oracle copies a small ChatGPT auth/Cloudflare allowlist to avoid oversized request headers; use <code>--browser-cookie-names</code> only when you need to override that set. Use the hidden <code>--browser-allow-cookie-errors</code> flag only when you’re intentionally running logged out (it skips the early exit but still warns).</li>
+<li>Attach-running mode is mutually exclusive with launcher-owned flags such as <code>--browser-manual-login</code>, <code>--browser-chrome-profile</code>, <code>--browser-cookie-path</code>, <code>--browser-hide-window</code>, <code>--browser-keep-browser</code>, and <code>--browser-port</code>. <code>--remote-chrome</code> is allowed in attach-running mode, but only as the local host:port hint used to find matching <code>DevToolsActivePort</code> metadata. <code>--browser-chrome-path</code> is accepted but ignored.</li>
+<li>Experimental cookie controls (hidden flags/env):</li>
+<li><code>--browser-cookie-names &lt;comma-list&gt;</code> or <code>ORACLE_BROWSER_COOKIE_NAMES</code>: override the default allowlist of cookies to sync. Useful when ChatGPT changes auth cookie names.</li>
+<li><code>--browser-cookie-wait &lt;ms|s|m&gt;</code>: if cookie sync fails or returns no cookies, wait once and retry (helps when macOS Keychain prompts are slow).</li>
+<li><code>--browser-inline-cookies &lt;jsonOrBase64&gt;</code> or <code>ORACLE_BROWSER_COOKIES_JSON</code>: skip Chrome/keychain and set cookies directly. Payload is a JSON array of DevTools <code>CookieParam</code> objects (or the same, base64-encoded). At minimum you need <code>name</code>, <code>value</code>, and either <code>url</code> or <code>domain</code>; we infer <code>path=/</code>, <code>secure=true</code>, <code>httpOnly=false</code>.</li>
+<li><code>--browser-inline-cookies-file &lt;path&gt;</code> or <code>ORACLE_BROWSER_COOKIES_FILE</code>: load the same payload from disk (JSON or base64 JSON). If no args/env are provided, Oracle also auto-loads <code>~/.oracle/cookies.json</code> or <code>~/.oracle/cookies.base64</code> when present.</li>
+<li>Practical minimal set that keeps ChatGPT logged in and avoids the workspace picker: <code>__Secure-next-auth.session-token</code> (include <code>.0</code>/<code>.1</code> variants) and <code>_account</code> (active workspace/account). Cloudflare proofs (<code>cf_clearance</code>, <code>__cf_bm</code>/<code>_cfuvid</code>/<code>CF_Authorization</code>/<code>__cflb</code>) are only needed when a challenge is active. In practice our allowlist pulls just two cookies (session token + <code>_account</code>) and works; add the Cloudflare names if you hit a challenge.</li>
+<li>Inline payload shape example (we ignore extra fields like <code>expirationDate</code>, <code>sameSite</code>, <code>hostOnly</code>):</li>
+<p>``<code>json [ { &quot;name&quot;: &quot;__Secure-next-auth.session-token&quot;, &quot;value&quot;: &quot;&lt;token&gt;&quot;, &quot;domain&quot;: &quot;chatgpt.com&quot;, &quot;path&quot;: &quot;/&quot;, &quot;secure&quot;: true, &quot;httpOnly&quot;: true, &quot;expires&quot;: 1771295753 }, { &quot;name&quot;: &quot;_account&quot;, &quot;value&quot;: &quot;personal&quot;, &quot;domain&quot;: &quot;chatgpt.com&quot;, &quot;path&quot;: &quot;/&quot;, &quot;secure&quot;: true, &quot;httpOnly&quot;: false, &quot;expires&quot;: 1770702447 } ] </code>``</p>
+</ul>
+<p>All options are persisted with the session so restarts (<code>oracle restart &lt;id&gt;</code>) reuse the same automation settings.</p>
+<h3 id="deep-research-mode"><a class="anchor" href="#deep-research-mode" aria-label="Anchor link">#</a>Deep Research mode</h3>
+<p>Use <code>--browser-research deep</code> when the task needs broad web discovery, source comparison, or a cited report:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-research</span><span style="color:#96D0FF"> deep</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Research the current browser support for WebGPU in enterprise-managed Chrome and cite sources."</span></span></code></pre>
+<p>Oracle activates ChatGPT Deep Research through the composer tools menu, recognizing both the <code>Deep research</code> label and current <code>Get a detailed report</code> menu variants. It waits for the research plan to auto-confirm, logs high-level progress, then captures the final report from the Deep Research report surface instead of trusting the assistant tool-call wrapper.</p>
+<p>If ChatGPT initially exposes only <code>Called tool</code> / <code>Used tool</code>, Oracle treats that as an incomplete capture for Deep Research rather than a final answer. Reattach the existing session with <code>oracle session &lt;id&gt; --render</code> so Oracle can recover the lazy-loaded report from the existing Chrome tab; do not rerun the research unless the browser session is unrecoverable.</p>
+<p>Deep Research is browser-only. It does not use connected apps in v1; give it public-web scope, uploaded files, and any domain/source guidance in the prompt. For deep thinking over code or architecture without web search, prefer a normal browser run with a Pro/Thinking model and <code>--browser-thinking-time heavy</code>.</p>
+<p>Completed browser sessions also save durable artifacts under <code>~/.oracle/sessions/&lt;id&gt;/artifacts/</code>. Deep Research writes the extracted report to <code>deep-research-report.md</code>, and every browser run writes <code>transcript.md</code> with the prompt, final answer, conversation URL, and saved artifact references. Use <code>--write-output &lt;path&gt;</code> when you also need a copy of just the final answer at a specific path.</p>
+<p>When ChatGPT generates downloadable files in the assistant response (for example a ZIP, wheel, source distribution, CSV, or PDF), Oracle saves those files beside the transcript before any archive attempt. The downloader is intentionally narrow: it only follows ChatGPT-owned file/download URLs from the assistant response and uses <code>sandbox:/mnt/data/...</code> links as source metadata and filename hints, not as arbitrary fetch targets. External links in the response are left in the transcript but are not downloaded. In bridge mode, a patched Windows host advertises artifact-transfer capability through <code>/health</code>; the Linux client then pulls each saved file over the authenticated bridge endpoint, stores it under the Linux session <code>artifacts/</code> directory, and verifies safe filename, byte size, SHA-256, and ZIP structure where applicable. If either side is older or transfer validation fails, the text response still completes and Oracle prints a manual-copy fallback instead of leaking host paths or signed download URLs.</p>
+<h3 id="conversation-archiving"><a class="anchor" href="#conversation-archiving" aria-label="Anchor link">#</a>Conversation archiving</h3>
+<p>Browser mode keeps the local session as the source of truth, so Oracle can optionally archive the ChatGPT conversation after a successful run. The default <code>--browser-archive auto</code> archives only successful non-project, non-Deep-Research, non-multi-turn one-shot chats after <code>transcript.md</code>, generated artifacts, the final answer, and the conversation URL are saved locally.</p>
+<p>Oracle does not auto-archive failed, incomplete, running, project, Deep Research, or multi-turn sessions. Use <code>--browser-archive never</code> to disable archiving, or <code>--browser-archive always</code> when you explicitly want a successful browser conversation archived even outside the default one-shot policy. Archived chats are still visible and manageable from ChatGPT&#39;s own archive UI.</p>
+<h3 id="chatgpt-project-sources"><a class="anchor" href="#chatgpt-project-sources" aria-label="Anchor link">#</a>ChatGPT Project Sources</h3>
+<p>ChatGPT Project Sources can act as explicit shared context for project workflows where chats should not implicitly share memory. This is especially useful with Developer Mode / Memory Off: separate chats do not see each other&#39;s conversation history, but they can read files attached to the Project Sources tab.</p>
+<p>Oracle exposes a narrow, non-destructive v1:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#768390"># Preview the upload plan without touching ChatGPT</span></span>
+<span class="line"><span style="color:#F69D50">oracle</span><span style="color:#96D0FF"> project-sources</span><span style="color:#96D0FF"> add</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --chatgpt-url</span><span style="color:#96D0FF"> "https://chatgpt.com/g/g-p-example/project"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> docs/architecture.md</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --dry-run</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#768390"># List current sources</span></span>
+<span class="line"><span style="color:#F69D50">oracle</span><span style="color:#96D0FF"> project-sources</span><span style="color:#96D0FF"> list</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --chatgpt-url</span><span style="color:#96D0FF"> "https://chatgpt.com/g/g-p-example/project"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#768390"># Append files to the Sources tab</span></span>
+<span class="line"><span style="color:#F69D50">oracle</span><span style="color:#96D0FF"> project-sources</span><span style="color:#96D0FF"> add</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --chatgpt-url</span><span style="color:#96D0FF"> "https://chatgpt.com/g/g-p-example/project"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> docs/architecture.md</span><span style="color:#96D0FF"> docs/decisions.md</span></span></code></pre>
+<p>This command uses browser automation but does not select a model, start a consult, or send a prompt. It only opens the Project Sources surface, lists existing files, or appends new files. Destructive operations such as delete, replace, and sync are intentionally left out until the UI path is safer and better covered by live tests.</p>
+<h3 id="multi-turn-browser-consults"><a class="anchor" href="#multi-turn-browser-consults" aria-label="Anchor link">#</a>Multi-turn browser consults</h3>
+<p>Use browser follow-ups when a one-shot review would be too easy for the model to answer shallowly. Oracle keeps the same ChatGPT conversation open, waits for each answer, then submits the next follow-up:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --model</span><span style="color:#96D0FF"> gpt-5.5-pro</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-thinking-time</span><span style="color:#96D0FF"> heavy</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Review this migration plan and identify the top risks."</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> docs/migration-plan.md</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-follow-up</span><span style="color:#96D0FF"> "Challenge your previous recommendation. What would fail in production?"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-follow-up</span><span style="color:#96D0FF"> "Now give the final decision with the smallest safe next step."</span></span></code></pre>
+<p>The CLI output and saved <code>transcript.md</code> include each captured turn. For PR validation, compare a one-shot run with the same initial prompt against a two-turn run that asks the model to challenge itself; record concrete differences such as additional failure modes, test cases, or rollback steps rather than claiming a fixed quality percentage.</p>
+<p>Guardrails for agents:</p>
+<ul>
+<li>Use one-shot browser runs for narrow bugs, exact file sets, quick code review, or when the expected answer is a short decision.</li>
+<li>Use explicit follow-ups for ambiguous architecture, competing options, product tradeoffs, or review flows where a challenge pass and final recommendation are useful.</li>
+<li>Use Deep Research for broad public-web research that needs citations; Deep Research has its own lifecycle and is not combined with browser follow-ups.</li>
+<li>Oracle never invents follow-ups automatically. Agents may suggest a short follow-up sequence, but the caller must pass each prompt explicitly with <code>--browser-follow-up</code> or <code>browserFollowUps</code>.</li>
+</ul>
+<h3 id="chatgpt-generated-images"><a class="anchor" href="#chatgpt-generated-images" aria-label="Anchor link">#</a>ChatGPT generated images</h3>
+<p>When ChatGPT returns downloadable generated images in browser mode, Oracle downloads them using the active browser cookies and records them as session artifacts. To choose an output path, pass <code>--generate-image &lt;file&gt;</code>:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --model</span><span style="color:#96D0FF"> "GPT-5.5 Pro"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --generate-image</span><span style="color:#96D0FF"> /tmp/oracle-image.png</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Create a simple product icon on a transparent background."</span></span></code></pre>
+<p>If ChatGPT returns multiple images, the first image saves to the requested path and the rest save as numbered siblings. Without <code>--generate-image</code>, Oracle writes images to the session <code>artifacts/</code> directory.</p>
+<p>MCP agents should prefer the <code>chatgpt_image</code> tool. It wraps the same behavior with a smaller input shape, uploads reference files by default, and returns saved files in <code>structuredContent.images</code>. Advanced callers can still pass <code>generateImage</code> to <code>consult</code> directly.</p>
+<h3 id="manual-login-mode-persistent-profile-no-cookie-copy"><a class="anchor" href="#manual-login-mode-persistent-profile-no-cookie-copy" aria-label="Anchor link">#</a>Manual login mode (persistent profile, no cookie copy)</h3>
+<p>Use <code>--browser-manual-login</code> when cookie decrypt is blocked (e.g., Windows app-bound cookies) or you prefer to sign in explicitly. You can also make it the default via <code>browser.manualLogin</code> in <code>~/.oracle/config.json</code>.</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-manual-login</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --browser-keep-browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --model</span><span style="color:#96D0FF"> "GPT-5.5 Pro"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Say hi"</span></span></code></pre>
+<ul>
+<li>Oracle launches Chrome headful with a persistent automation profile at <code>~/.oracle/browser-profile</code> (override with <code>ORACLE_BROWSER_PROFILE_DIR</code> or <code>browser.manualLoginProfileDir</code> in <code>~/.oracle/config.json</code>).</li>
+<li>Log into chatgpt.com in that window the first time; Oracle polls until the session is active, then proceeds.</li>
+<li>Reuse the same profile on subsequent runs (no re-login unless the session expires).</li>
+<li>Add <code>--browser-keep-browser</code> (or config <code>browser.keepBrowser=true</code>) when doing the initial login/setup or debugging so the Chrome window stays open after the run. When omitted, Oracle closes Chrome but preserves the profile on disk.</li>
+<li>Cookie copy is skipped by default in this mode. To automate manual-login runs, set <code>browser.manualLoginCookieSync=true</code> in <code>~/.oracle/config.json</code> to seed the persistent profile from your existing Chrome cookies; inline cookies apply when cookie sync is enabled.</li>
+<li>If Chrome is already running with that profile and DevTools remote debugging enabled (see <code>DevToolsActivePort</code> in the profile dir), you can reuse it instead of relaunching by pointing Oracle at it with <code>--remote-chrome &lt;host:port&gt;</code>.</li>
+<li>Remote Chrome runs also participate in tab-slot coordination when paired with <code>--browser-manual-login</code> and a shared manual-login profile.</li>
+</ul>
+<h3 id="concurrent-agents-and-long-pro-runs"><a class="anchor" href="#concurrent-agents-and-long-pro-runs" aria-label="Anchor link">#</a>Concurrent agents and long Pro runs</h3>
+<p>When Codex, Claude Code, or another Oracle caller share the same manual-login profile, each browser run now acquires a tab slot before opening a ChatGPT tab. The default allows three simultaneous ChatGPT tabs; the fourth caller waits instead of failing because another agent is already using the browser. This is most useful for long Pro/Thinking runs where one agent may wait for a response while another agent needs to start a separate consult.</p>
+<p>Use <code>--browser-max-concurrent-tabs &lt;n&gt;</code>, <code>browser.maxConcurrentTabs</code>, or <code>ORACLE_BROWSER_MAX_CONCURRENT_TABS</code> to tune the soft limit. Precedence is explicit CLI/config value, then environment, then the default of <code>3</code>; invalid or non-positive environment values fall back instead of disabling the cap. Keep the value modest: too many concurrent ChatGPT tabs can make the UI unstable or trigger account-side throttling. Oracle also serializes manual-login Chrome startup for the shared profile, then reuses the first reachable DevTools session instead of racing multiple Chrome launches against the same <code>user-data-dir</code>. The short profile lock still serializes the send/upload moment so separate agents do not type into the same composer.</p>
+<p>For live concurrency smoke, the most stable path is one already-running signed-in Chrome with remote debugging enabled, plus <code>--remote-chrome &lt;host:port&gt;</code>. Direct parallel launch is supported defensively, but a persistent shared Chrome gives clearer ownership and avoids account/login churn across agents.</p>
+<h2 id="remote-chrome-sessions-headless-server-workflows"><a class="anchor" href="#remote-chrome-sessions-headless-server-workflows" aria-label="Anchor link">#</a>Remote Chrome Sessions (headless/server workflows)</h2>
+<p>Oracle can reuse an already-running Chrome/Edge instance on another machine by tunneling over the Chrome DevTools Protocol. This is handy when:</p>
+<ul>
+<li>Your CLI runs on a headless server (Linux/macOS CI, remote mac minis, etc.) but you want the browser UI to live on a desktop where you can see uploads or respond to Captcha challenges.</li>
+<li>You want to keep a single signed-in profile open (e.g., Windows VM with company SSO) while sending prompts from other hosts.</li>
+</ul>
+<h3 id="1-start-chrome-with-remote-debugging-enabled"><a class="anchor" href="#1-start-chrome-with-remote-debugging-enabled" aria-label="Anchor link">#</a>1. Start Chrome with remote debugging enabled</h3>
+<p>On the machine that should host the browser window:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">google-chrome</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --remote-debugging-port=9222</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --remote-debugging-address=0.0.0.0</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --user-data-dir=/path/to/profile</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --profile-directory=</span><span style="color:#96D0FF">'Default'</span></span></code></pre>
+<p>Notes:</p>
+<ul>
+<li>Any Chromium flavor works (Chrome, Edge, Vivaldi, etc.)—just ensure CDP is exposed on a reachable host:port. Linux distributions often call the binary <code>google-chrome-stable</code>. On macOS you can run <code>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</code>.</li>
+<li><code>--remote-debugging-address=0.0.0.0</code> is required if the CLI connects from another machine. Lock it down behind a VPN or SSH tunnel if the network is untrusted.</li>
+<li>Keep this browser window open and signed into ChatGPT; Oracle will reuse that session and <strong>will not</strong> copy cookies over the wire.</li>
+</ul>
+<h3 id="2-point-oracle-at-the-remote-browser"><a class="anchor" href="#2-point-oracle-at-the-remote-browser" aria-label="Anchor link">#</a>2. Point Oracle at the remote browser</h3>
+<p>From the machine running <code>oracle</code>:</p>
+<pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --remote-chrome</span><span style="color:#96D0FF"> 192.168.1.10:9222</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --prompt</span><span style="color:#96D0FF"> "Summarize the latest incident doc"</span><span style="color:#F47067"> \</span></span>
+<span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> docs/incidents/latest.md</span></span></code></pre>
+<p>Key behavior:</p>
+<ul>
+<li>Use IPv6 by wrapping the host in brackets, e.g. <code>--remote-chrome &quot;[2001:db8::1]:9222&quot;</code>.</li>
+<li>Local-only flags like <code>--browser-headless</code>, <code>--browser-hide-window</code>, <code>--browser-keep-browser</code>, and <code>--browser-chrome-path</code> are ignored because Oracle no longer launches Chrome. You still get verbose logging, model switching, attachment uploads, and markdown capture.</li>
+<li>Cookie sync is skipped automatically (the remote browser already has cookies). If you need inline cookies, use them on the machine that’s actually running Chrome.</li>
+<li>Oracle opens a dedicated CDP target (new tab) for each run and closes it afterward so your existing tabs stay untouched.</li>
+<li>When remote runs are served by an Oracle host with a manual-login profile, the host-side tab lease registry applies the same concurrent tab limit.</li>
+<li>Attachments are transferred via CDP: Oracle reads each file locally, base64-encodes it, and uses <code>DataTransfer</code> inside the remote browser to populate the upload field. Files larger than 20 MB are rejected to keep CDP messages reasonable.</li>
+<li>When the remote WebSocket disconnects, Oracle errors with “Remote Chrome connection lost…” so you can re-run after restarting the browser.</li>
+</ul>
+<h3 id="3-troubleshooting"><a class="anchor" href="#3-troubleshooting" aria-label="Anchor link">#</a>3. Troubleshooting</h3>
+<ul>
+<li>Run <code>scripts/test-remote-chrome.ts &lt;host&gt; [port]</code> to sanity-check connectivity (<code>npx tsx scripts/test-remote-chrome.ts my-host 9222</code>).</li>
+<li>If you target IPv6 without brackets (e.g., <code>2001:db8::1:9222</code>), the CLI rejects it—wrap the address like <code>[2001:db8::1]:9222</code>.</li>
+<li>Ensure firewalls allow inbound TCP to the debugging port and that you’re not behind a captive proxy stripping WebSocket upgrades.</li>
+<li>Because we do not control the remote lifecycle, Chrome stays running after the session. Shut it down manually when you’re done or remove <code>--remote-debugging-port</code> to stop exposing CDP.</li>
+</ul>
+<h3 id="remote-service-mode-oracle-serve"><a class="anchor" href="#remote-service-mode-oracle-serve" aria-label="Anchor link">#</a>Remote Service Mode (<code>oracle serve</code>)</h3>
+<p>Prefer to keep Chrome entirely on the remote Mac (no DevTools tunneling, no manual cookie shuffling)? Use the built-in service:</p>
+<ol>
+<li><strong>Start the host</strong></li>
+</ol>
+<p>``<code>bash oracle serve </code>``</p>
+<p>Oracle picks a free port, launches Chrome, starts an HTTP/SSE API, and prints:</p>
+<p>``<code> Listening at 0.0.0.0:9473 Access token: c4e5f9... </code>``</p>
+<p>Use <code>--host</code>, <code>--port</code>, or <code>--token</code> to override the defaults if needed. If the host Chrome profile is not signed into ChatGPT, the service opens chatgpt.com for login and exits—sign in, then restart <code>oracle serve</code>.</p>
+<ol>
+<li><strong>Run from your laptop</strong></li>
+</ol>
+<p>``<code>bash oracle --engine browser \ --remote-host 192.168.64.2:9473 \ --remote-token c4e5f9... \ --prompt &quot;Summarize the incident doc&quot; \ --file docs/incidents/latest.md </code>``</p>
+<ul>
+<li><code>--remote-host</code> points the CLI at the VM.</li>
+<li><code>--remote-token</code> matches the token printed by <code>oracle serve</code> (set <code>ORACLE_REMOTE_TOKEN</code> to avoid repeating it).</li>
+<li>You can also set defaults in <code>~/.oracle/config.json</code> (<code>browser.remoteHost</code>, <code>browser.remoteToken</code>) so you don’t need the flags; env vars still override those when present.</li>
+<li>Cookies are <strong>not</strong> transferred from your laptop. The service requires the host Chrome profile to be signed in; if not, it opens chatgpt.com and exits so you can log in, then restart <code>oracle serve</code>.</li>
+</ul>
+<ol>
+<li><strong>What happens</strong></li>
+</ol>
+<ul>
+<li>The CLI assembles the composed prompt + file bundle locally, sends them to the VM, and streams log lines/answer text back through the same HTTP connection.</li>
+<li>The remote host runs Chrome locally, pulls ChatGPT cookies from its own Chrome profile, and reuses them across runs while the service is up. If cookies are missing, the service exits after opening chatgpt.com so you can sign in before restarting.</li>
+<li>Background/detached sessions (<code>--no-wait</code>) are disabled in remote mode so the CLI can keep streaming output.</li>
+<li><code>oracle serve</code> logs the DevTools port of the manual-login Chrome (e.g., <code>Manual-login Chrome DevTools port: 54371</code>). Runs automatically attach to that logged-in Chrome; you can use the printed port/JSON URL for debugging if needed.</li>
+</ul>
+<ol>
+<li><strong>Stop the host</strong></li>
+</ol>
+<ul>
+<li><code>Ctrl+C</code> on the VM shuts down the HTTP server and Chrome. Restart <code>oracle serve</code> whenever you need a new session; omit <code>--token</code> to let it rotate automatically.</li>
+</ul>
+<p>This mode is ideal when you have a macOS VM (or spare Mac mini) logged into ChatGPT and you just want to run the CLI from another machine without ever copying profiles or keeping Chrome visible locally.</p>
+<h2 id="limitations-follow-up-plan"><a class="anchor" href="#limitations-follow-up-plan" aria-label="Anchor link">#</a>Limitations / Follow-Up Plan</h2>
+<ul>
+<li><strong>Attachment lifecycle</strong> – in <code>auto</code> mode we prefer inlining files into the composer (fewer moving parts). When we do upload, each <code>--file</code> path is uploaded separately (or bundled) so ChatGPT can ingest filenames/content. The automation waits for uploads to finish (send button enabled, upload chips visible) before submitting. When inline paste is rejected by ChatGPT (too large), Oracle retries automatically with uploads.</li>
+<li><strong>Model picker drift</strong> – we rely on heuristics to pick GPT-5.6 / GPT-5.5 / GPT-5.4 / GPT-5.2 variants. If OpenAI changes the DOM we need to refresh the selectors quickly. Consider snapshot tests or a small “self check” command.</li>
+<li><strong>Non-mac platforms</strong> – window hiding uses AppleScript today; Linux/Windows just ignore the flag. We should detect platforms explicitly and document the behavior.</li>
+<li><strong>Streaming UX</strong> – browser runs cannot stream tokens, so we emit heartbeat/status logs while waiting. Investigate whether we can stream clipboard deltas via mutation observers for a closer UX.</li>
+</ul>
+<h2 id="testing-notes"><a class="anchor" href="#testing-notes" aria-label="Anchor link">#</a>Testing Notes</h2>
+<ul>
+<li>ChatGPT automation smoke: <code>pnpm test:browser</code></li>
+<li>Gemini web (cookie) smoke: <code>ORACLE_LIVE_TEST=1 pnpm vitest run tests/live/gemini-web-live.test.ts</code> (requires a signed-in Chrome profile at <code>gemini.google.com</code>)</li>
+<li><code>pnpm test --filter browser</code> does not exist yet; manual runs with <code>--engine browser -v</code> are the current validation path.</li>
+<li>Most of the heavy lifting lives in <code>src/browserMode.ts</code>. If you change selectors or the mutation observer logic, run a local <code>oracle --engine browser --browser-keep-browser</code> session so you can inspect DevTools before cleanup.</li>
+</ul><nav class="page-nav" aria-label="Pager"><a class="page-nav-prev" href="grok.html"><small>Previous</small><span>Grok 4.1 (xAI) Support</span></a><a class="page-nav-next" href="chromium-forks.html"><small>Next</small><span>Chromium-based browsers (Chromium, Edge, Brave variants)</span></a></nav></article>
+        <nav class="toc" aria-label="On this page"><h2>On this page</h2><a class="toc-l2" href="#quick-example-browser-mode-with-custom-cookies">Quick example: browser mode with custom cookies</a><a class="toc-l2" href="#quick-example-attach-to-your-running-chrome">Quick example: attach to your running Chrome</a><a class="toc-l2" href="#current-pipeline">Current Pipeline</a><a class="toc-l3" href="#cli-options">CLI Options</a><a class="toc-l3" href="#deep-research-mode">Deep Research mode</a><a class="toc-l3" href="#conversation-archiving">Conversation archiving</a><a class="toc-l3" href="#chatgpt-project-sources">ChatGPT Project Sources</a><a class="toc-l3" href="#multi-turn-browser-consults">Multi-turn browser consults</a><a class="toc-l3" href="#chatgpt-generated-images">ChatGPT generated images</a><a class="toc-l3" href="#manual-login-mode-persistent-profile-no-cookie-copy">Manual login mode (persistent profile, no cookie copy)</a><a class="toc-l3" href="#concurrent-agents-and-long-pro-runs">Concurrent agents and long Pro runs</a><a class="toc-l2" href="#remote-chrome-sessions-headless-server-workflows">Remote Chrome Sessions (headless/server workflows)</a><a class="toc-l3" href="#1-start-chrome-with-remote-debugging-enabled">1. Start Chrome with remote debugging enabled</a><a class="toc-l3" href="#2-point-oracle-at-the-remote-browser">2. Point Oracle at the remote browser</a><a class="toc-l3" href="#3-troubleshooting">3. Troubleshooting</a><a class="toc-l3" href="#remote-service-mode-oracle-serve">Remote Service Mode (oracle serve)</a><a class="toc-l2" href="#limitations-follow-up-plan">Limitations / Follow-Up Plan</a><a class="toc-l2" href="#testing-notes">Testing Notes</a></nav>
+      </div>
+    </main>
+  </div>
+  <script>
+const themeRoot=document.documentElement;
+function applyTheme(mode){themeRoot.dataset.theme=mode;document.querySelectorAll('[data-theme-toggle]').forEach(b=>b.setAttribute('aria-pressed',mode==='dark'?'true':'false'))}
+function storedTheme(){try{return localStorage.getItem('theme')}catch(e){return null}}
+function persistTheme(mode){try{localStorage.setItem('theme',mode)}catch(e){}}
+applyTheme(themeRoot.dataset.theme==='dark'?'dark':'light');
+document.querySelectorAll('[data-theme-toggle]').forEach(btn=>{btn.addEventListener('click',()=>{const next=themeRoot.dataset.theme==='dark'?'light':'dark';applyTheme(next);persistTheme(next)})});
+const systemDark=window.matchMedia&&matchMedia('(prefers-color-scheme: dark)');
+function onSystemChange(e){if(storedTheme())return;applyTheme(e.matches?'dark':'light')}
+if(systemDark){if(systemDark.addEventListener)systemDark.addEventListener('change',onSystemChange);else if(systemDark.addListener)systemDark.addListener(onSystemChange)}
+const sidebar=document.querySelector('.sidebar');
+const toggle=document.querySelector('.nav-toggle');
+const mobileNav=window.matchMedia('(max-width: 900px)');
+const sidebarFocusable='a[href],button,input,select,textarea,[tabindex]';
+function setSidebarFocusable(enabled){
+  sidebar?.querySelectorAll(sidebarFocusable).forEach((el)=>{
+    if(enabled){
+      if(el.dataset.sidebarTabindex!==undefined){
+        if(el.dataset.sidebarTabindex)el.setAttribute('tabindex',el.dataset.sidebarTabindex);
+        else el.removeAttribute('tabindex');
+        delete el.dataset.sidebarTabindex;
+      }
+    }else if(el.dataset.sidebarTabindex===undefined){
+      el.dataset.sidebarTabindex=el.getAttribute('tabindex')??'';
+      el.setAttribute('tabindex','-1');
+    }
+  });
+}
+function setSidebarOpen(open){
+  if(!sidebar||!toggle)return;
+  sidebar.classList.toggle('open',open);
+  toggle.setAttribute('aria-expanded',open?'true':'false');
+  if(mobileNav.matches){
+    sidebar.inert=!open;
+    if(open)sidebar.removeAttribute('aria-hidden');
+    else sidebar.setAttribute('aria-hidden','true');
+    setSidebarFocusable(open);
+  }else{
+    sidebar.inert=false;
+    sidebar.removeAttribute('aria-hidden');
+    setSidebarFocusable(true);
+  }
+}
+setSidebarOpen(false);
+toggle?.addEventListener('click',()=>setSidebarOpen(!sidebar?.classList.contains('open')));
+document.addEventListener('click',(e)=>{if(!sidebar?.classList.contains('open'))return;if(sidebar.contains(e.target)||toggle?.contains(e.target))return;setSidebarOpen(false)});
+document.addEventListener('keydown',(e)=>{if(e.key==='Escape')setSidebarOpen(false)});
+const syncSidebarForViewport=()=>setSidebarOpen(sidebar?.classList.contains('open')??false);
+if(mobileNav.addEventListener)mobileNav.addEventListener('change',syncSidebarForViewport);
+else mobileNav.addListener?.(syncSidebarForViewport);
+const input=document.getElementById('doc-search');
+input?.addEventListener('input',()=>{const q=input.value.trim().toLowerCase();document.querySelectorAll('nav section').forEach(sec=>{let any=false;sec.querySelectorAll('.nav-link').forEach(a=>{const m=!q||a.textContent.toLowerCase().includes(q);a.style.display=m?'block':'none';if(m)any=true});sec.style.display=any?'block':'none'})});
+function attachCopy(target,getText){const btn=document.createElement('button');btn.type='button';btn.className='copy';btn.textContent='Copy';btn.addEventListener('click',async()=>{try{await navigator.clipboard.writeText(getText());btn.textContent='Copied';btn.classList.add('copied');setTimeout(()=>{btn.textContent='Copy';btn.classList.remove('copied')},1400)}catch{btn.textContent='Failed';setTimeout(()=>{btn.textContent='Copy'},1400)}});target.appendChild(btn)}
+document.querySelectorAll('.doc pre').forEach(pre=>attachCopy(pre,()=>pre.querySelector('code')?.textContent??''));
+document.querySelectorAll('.home-install').forEach(el=>attachCopy(el,()=>el.querySelector('code')?.textContent??''));
+const tocLinks=document.querySelectorAll('.toc a');
+if(tocLinks.length){const map=new Map();tocLinks.forEach(a=>{const id=a.getAttribute('href').slice(1);const el=document.getElementById(id);if(el)map.set(el,a)});const setActive=l=>{tocLinks.forEach(x=>x.classList.remove('active'));l.classList.add('active')};const obs=new IntersectionObserver(entries=>{const visible=entries.filter(e=>e.isIntersecting).sort((a,b)=>a.boundingClientRect.top-b.boundingClientRect.top);if(visible.length){const link=map.get(visible[0].target);if(link)setActive(link)}},{rootMargin:'-15% 0px -65% 0px',threshold:0});map.forEach((_,el)=>obs.observe(el))}
+</script>
+</body>
+</html>