@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/attach_app.md

@@ -0,0 +1,595 @@
+# api.attach_app(surface=None, env=None, present=None, preparing=None, config=None, show=None) -> dict
+
+<!-- group: Driving a surface -->
+
+Launch this workspace's own application and drive it. **Requires permission.**
+
+For a product that is not a web page: an Electron app, an iOS app on the
+Simulator (`kind: ios`), or an Android app on the Emulator (`kind: android`).
+`widgex.yml` names which with `kind`.
+
+## Why this exists rather than `drive`
+
+A web app can be started any way at all — `npm run dev` in a shell, a deployed
+URL, a file on disk — and reached *afterwards* with `api.drive(url, why)`.
+Nothing about how it started has to be known.
+
+An Electron app can only be attached to if `--remote-debugging-port` was on its
+command line **at spawn**. There is no attaching to one that is already running.
+So "how does this app start" stops being a convenience and becomes the
+precondition of the app being observable at all — and that is why it is declared
+in a file that everyone shares rather than improvised by whichever session got
+there first.
+
+## Never the copy they are running
+
+The user is usually working *in* the application you are changing, or in one
+beside it. This call starts a **separate** copy, with its own profile and
+debugging port, so they can judge your change without leaving what they were
+doing.
+
+**Never deploy into, overwrite, or ask for a reload of the application the user
+is running** — not to check your work, not to "just quickly look", and not as a
+fallback when attaching fails. A reload costs them their place and their train
+of thought, and installing over a running app means every session on that
+machine is now running your half-finished change. When attaching fails, report
+it and say what you could not confirm: a wrong spec is worth fixing, and
+restarting their editor to save yourself a diagnosis is not.
+
+## It builds first
+
+`app.build` runs before every spawn, so what you attach to is the code you just
+changed. If the build fails the call refuses rather than handing you the copy
+that was already running — a preview of the previous build, presented as your
+change, is worse than no preview.
+
+## Writing the file for a project that has none
+
+Work out how the app already starts — its package scripts, its launch
+configuration, how a developer runs it by hand — and propose a `widgex.yml`
+from that.
+
+**Never ask the project to change itself to be testable.** No markers to add, no
+preload script, no test-only build, no flag in their source. Selecting on markup
+the app already renders is fine; requiring it to render something new for your
+benefit is not. If a project cannot be previewed without changing it, say so —
+that is a real answer, and a spec that quietly cannot work is not.
+
+The requirement is one thing: a Chromium you can attach to. `app.kind` says
+which of two ways it gets one:
+
+- `kind: electron` — the app *is* Chromium and takes a debugging port on its
+  command line at spawn. There is no attaching to one already running, which is
+  why how it starts has to be declared.
+- `kind: web` — `app.serve` boots the dev server and a browser is pointed at
+  `app.url`. Both carry `{port}`, which is allocated per preview: never write a
+  fixed one, because it works from a single worktree and then silently drives
+  that server from a second one.
+
+Either way the app has to let its profile and single-instance behaviour be set
+from outside, and show a surface you can pick out of markup it already renders.
+A native binary or a canvas-only interface meets none of that and cannot be
+driven by configuration alone. Say that plainly rather than writing a file that
+will fail at the first attach.
+
+## The file
+
+`widgex.yml`, at the workspace root. The minimum:
+
+```yaml
+app:
+  kind: electron
+  exec: node_modules/.bin/electron
+  args: ['.']
+```
+
+Everything else is optional:
+
+```yaml
+app:
+  build: [pnpm, build]        # run before a spawn, never before a reuse
+  debugPort: '--remote-debugging-port={port}'
+  envPolicy: inherit          # or `allowlist` to keep only the bare minimum
+  env:
+    NODE_ENV: development
+  profile:
+    arg: --user-data-dir      # or:  env: SOME_APP_HOME
+    files:                    # seeded into the profile before the app starts
+      settings.json: '{"skipOnboarding": true}'
+  target:
+    urlIncludes: index.html
+```
+
+## Which machine it runs on
+
+`surface` picks a window to look at. `env` picks the *machine* to run on, and
+they are different questions.
+
+```yaml
+app:
+  environments:
+    fresh:
+      description: A machine that has never run an agent CLI.
+      home: isolated
+      profile: fresh
+    returning:
+      home: inherit
+```
+
+`home: isolated` gives the app its own home directory **and a different value
+for `$USER`**, so it finds nothing of yours — no CLI config in your home, no
+credential in your keychain. Both halves are needed and the second is the one
+that is easy to miss: on macOS the keychain is per-user, not per-home, so a home
+swap alone leaves a "fresh" machine still finding the credentials you signed in
+with. Measured, not assumed.
+
+Be precise about what the second half is, because this page used to say "its own
+user" and that reads as more than it is. It is `HOME` and `USER`, two
+environment variables. There is no account, no uid, nothing the kernel enforces.
+It defeats a probe that reads `$USER` — which is exactly what Claude Code's
+`security find-generic-password -a $USER` does, and why it works — and it
+defeats nothing that asks the operating system who it really is. `PATH` is
+inherited either way, so an isolated machine still *finds* your installed CLIs;
+what it does not find is their credentials.
+
+**`home: inherit` is not the default. Naming no environment at all is.** They
+behave the same and they are not the same code path: with no `env=` the spec
+carries no environment, so the block above is never consulted and `HOME`/`USER`
+are never touched. The app runs here, on your machine, and sees everything you
+see — your home, your CLIs, your keychain — while opening your own checkout.
+A separate process with a separate profile and a separate port is not a separate
+machine, and the attach result now says which you got.
+
+`profile: fresh` throws the app's own state away before each launch. It is a
+different question from `home`: `home` hides *your* machine from the app, and
+the profile is what the environment's own last run left behind. Without it a
+first-run test is a first run exactly once — the next launch restores a profile
+that has already been through onboarding, and says nothing about it. `persist`
+is the default, and is what `returning` wants.
+
+Two more optional keys:
+
+- **`files`** — seeded into the environment's home before the app starts.
+  Relative paths only, nothing escaping the root. `{home}` is substituted.
+- **`setup`** — commands run once when the machine is built, each a list of
+  arguments rather than a shell string. Re-run only when `files`, `env` or
+  `setup` change; a failure refuses the attach rather than handing back a
+  half-built machine.
+
+Each environment is its own instance and its own profile, so two of them run
+side by side without seeing each other.
+
+### Why you want one
+
+Testing a first run on your own machine does not test a first run. It tests
+your machine. That mistake produced a report saying the setup wizard's
+first-run flow was fine — it had never been exercised, because the wizard found
+the developer's own CLI and opened on "already connected", and nothing in the
+run said so.
+
+### Paths
+
+`exec` is resolved against the workspace when it is relative. `{root}`
+substitutes the workspace folder anywhere in `exec` or `args`, and `${VAR}`
+expands from the environment the app will run with — an unset one is an error
+rather than an empty string, because expanding it away produces a failure much
+later that names nothing.
+
+If `exec` names a macOS `.app` bundle, the executable inside it is found for
+you; its name is the branding's, not something you should have to write down.
+
+### `profile.files`
+
+Files written into the profile directory before the app starts, with `{port}`
+substituted. Some apps cannot be tested without one — a marker that skips
+onboarding, a preset config, a feature flag. Contents are written verbatim and
+nothing is merged. Paths may not escape the profile directory.
+
+WidgeX's own `widgex.yml` uses this for `argv.json`, which is how a spawned
+instance learns the debugging port it was started with.
+
+### `debugPort` is a template
+
+`{port}` is filled in. Put the literal token `{debugPort}` in `args` to control
+*where* it lands, because position matters: `electron . --remote-debugging-port=N`
+can reach the app as its own argv rather than Chromium's.
+
+For a command whose arguments we cannot compose — `make dev`, a shell script, a
+task runner — use the escape hatch:
+
+```yaml
+  debugPort:
+    env: WIDGEX_DEBUG_PORT
+```
+
+Nothing is added to the command line; the variable is exported and **your script
+must forward it**. That is one line in your own file, and it is the only way a
+wrapped launch is testable at all. Forget it and the failure is "started but
+never opened a window", which looks like four other things.
+
+### `profile`
+
+Where the app keeps its own state, so two branches testing at once do not share
+one. Omit it and they do.
+
+### `target` and `surfaces`
+
+`target` is the default, used when you call `attach_app()` with no argument.
+`surfaces` names things you can ask for individually:
+
+```yaml
+  surfaces:
+    prefs:
+      titleIncludes: Preferences
+    dashboard:
+      includeFrames: true
+      documentMatches: '#dashboard-root'
+```
+
+Then `api.attach_app(surface='prefs')`. A name the file does not declare is
+refused with the list of ones it does.
+
+### More than one app in one repository
+
+`config` picks *which app*, where `surface` picks a window inside it. A
+repository often holds two things worth previewing — a desktop app and the
+website that documents it — and they share nothing: a different `kind`, a
+different way of starting, different surfaces. So each goes under `apps:`, by
+name, carrying a whole definition in the same shape as `app:`:
+
+```yaml
+app:                            # the default, used when no config is named
+  kind: electron
+  exec: node_modules/.bin/electron
+
+apps:
+  website:
+    kind: web
+    serve: [npm, run, docs, --, --port={port}]
+    url: http://localhost:{port}
+```
+
+Then `api.attach_app(config='website')`. A name is a whole definition and not
+a patch over `app:` — merging would mean every field needing a rule about
+which side wins, and a reader never being sure what a name actually launches.
+
+Two configurations are two instances, so a website preview and a desktop
+preview can be up at once without either standing in for the other. A name the
+file does not declare is refused with the ones it does; asking for one when
+there is no `apps:` block prints the block to write.
+
+Either can select three ways:
+
+- `urlIncludes` / `titleIncludes` — free, straight out of the target listing.
+- `documentMatches` — a CSS selector asked of the document itself, for targets
+  that cannot be told apart from outside. Costs a connection per candidate, so
+  it runs after the other two have narrowed the field. It reaches one frame deep,
+  because an app's real markup is often inside one.
+- `includeFrames` — also consider frame targets. Off by default: an embedded
+  player or OAuth widget is a target too, and driving one by accident looks like
+  driving the app while touching almost none of it.
+
+If several match and nothing distinguishes them, this refuses and lists them
+rather than picking. An app with a splash screen would otherwise hand you the
+splash screen, and every check you ran against it would pass.
+
+WidgeX's own `widgex.yml` uses `documentMatches` for its `panel` and `chat`
+surfaces: VS Code reports both as `vscode-webview://<uuid>` with an empty title,
+so only the document can say which is which.
+
+It also declares `workbench`, which is the *window* rather than a webview in it
+— the command palette, the notifications, the tabs, the menus. Reach for it
+whenever what you are verifying is a contributed command rather than something
+drawn in a panel: a keystroke sent to a webview frame is delivered to the frame,
+which has no keybinding service, so `api.press('Control+Shift+P')` on `panel`
+does exactly nothing and says so in no way at all.
+
+```python
+await api.attach_app(surface='workbench')
+await api.press('Control+Shift+P')
+await api.type_text('>My Command')
+```
+
+The same shape applies to any Electron-hosted editor, and it is the reason the
+app-target listing excludes only DevTools and extension pages rather than every
+scheme an IDE uses internally: on the app's own debugging port, the window is
+not "internal", it is the app.
+
+A window surface is also the one you can screenshot directly. A frame is an
+out-of-process iframe, and `Page.captureScreenshot` refuses one outright —
+`api.screenshot()` on `panel` works only because it quietly shoots the window
+containing it, and hands you the whole window rather than the panel.
+
+## An iOS app: `kind: ios`
+
+For an app that runs on the iOS Simulator (Swift, React Native, Expo,
+Flutter). On macOS with Xcode, `attach_app()` boots the simulator **without
+opening Simulator.app**, builds, installs and launches the app. The device's
+screen then shows up in a tab in this task's workbench, where the person can
+tap, swipe, scroll and type into it. No window opens anywhere else.
+
+```yaml
+app:
+  kind: ios
+  device: iPhone 17                 # name or UDID; default: a booted iPhone, else the newest
+  build: [xcodebuild, -scheme, MyApp, -sdk, iphonesimulator,
+          -destination, 'generic/platform=iOS Simulator', -derivedDataPath, build]
+  app: build/Build/Products/Debug-iphonesimulator/MyApp.app   # `*` allowed in a segment
+  bundleId: com.example.MyApp       # optional: read from the .app when absent
+```
+
+Every field is optional:
+- With no `build`, the app was built some other way.
+- With no `app`, the app is already installed and only `bundleId` is launched.
+- With neither, you just get the device.
+
+An Expo or React Native project whose own command builds and installs can leave
+`app` out and launch by `bundleId`:
+
+```yaml
+app:
+  kind: ios
+  build: [npx, expo, run:ios, --no-bundler]
+  bundleId: com.example.myapp
+```
+
+`exec`, `args`, `serve` and `url` are refused: a simulator has no program to
+run and no page to point at.
+
+**Any booted simulator gets a tab, however it was booted.** If you boot one
+with `xcrun simctl boot` or `npx expo run:ios` from `api.bash`, it appears in
+the workbench of the task on screen within a few seconds. `attach_app` exists
+so that the tab lands in *your* task and the app is built and launched for you.
+
+**The page verbs do not reach a simulator.** `api.click`, `api.outline` and
+friends are CDP, and a simulator has no markup. Use `xcrun simctl` through
+`api.bash` with the returned `device.udid`:
+- `xcrun simctl io <udid> screenshot shot.png` takes a picture you can look at.
+- `xcrun simctl openurl <udid> <url>` follows a deep link.
+- `xcrun simctl launch --terminate-running-process <udid> <bundleId>` relaunches the app.
+
+To check that something works by touch, ask the person. They can use the
+device in the tab.
+
+Returns `{status: 'attached', kind: 'ios', device: {name, os, udid},
+booted_by_widgex, stream_id, shown, note}`. `shown` says whether this task's
+workbench is the one on screen.
+
+## An Android app: `kind: android`
+
+The same idea for the Android Emulator, on any OS with the Android SDK
+installed. `attach_app()` does five things:
+1. Starts the AVD **with no emulator window**, or uses it if it is already
+   running.
+2. Waits for Android to finish booting.
+3. Builds the app.
+4. Installs the APK.
+5. Opens the app.
+
+The emulator's screen is a tab in this task's workbench. Tapping, swiping,
+scrolling and typing all work there, and the tab has Back, Home, Recents and
+Power.
+
+```yaml
+app:
+  kind: android
+  avd: Pixel_8                        # default: a running emulator, else the first AVD
+  build: [./gradlew, assembleDebug]
+  apk: app/build/outputs/apk/debug/app-debug.apk   # `*` allowed in a segment
+  package: com.example.myapp          # optional: read from the APK when absent
+  activity: .MainActivity             # optional: default is the launcher activity
+```
+
+For Expo or React Native, whose own command builds and installs:
+
+```yaml
+app:
+  kind: android
+  build: [npx, expo, run:android, --no-bundler]
+  package: com.example.myapp
+```
+
+Every field is optional, with the same meanings as for iOS. `exec`, `args`,
+`serve` and `url` are refused.
+
+**Any running emulator gets a tab, however it was started:** from `api.bash`
+(`emulator -avd Pixel_8`), by `npx expo run:android`, or from Android Studio's
+Device Manager.
+
+Drive it with `adb -s <serial>` through `api.bash`. The page verbs do not
+reach it.
+- `adb -s emulator-5554 exec-out screencap -p > shot.png` takes a picture.
+- `adb -s emulator-5554 shell am start -a android.intent.action.VIEW -d <url>`
+  follows a deep link.
+
+Returns `{status: 'attached', kind: 'android', device: {name, os, avd,
+serial}, booted_by_widgex, stream_id, shown, note}`.
+
+## Saying a demo is coming: `preparing`
+
+The window opens before your first `instruct` is written, and writing one takes
+however long you take. Until this, the app came up in front of somebody with
+nothing on it to say why — and the first thing they saw was a card appearing out
+of nowhere some seconds later.
+
+So attaching draws the assistant straight away, saying what is being prepared:
+
+```python
+await api.attach_app(surface='panel', preparing='the drafts autosave')
+```
+
+Omit it and he says *"Preparing your demo…"*, which is true. He is not given a
+feature name guessed from the surface: the surface is a panel, not the thing you
+changed. Your first `instruct` replaces him wherever he has got to.
+
+He is drawn in the **window**, not in the surface being driven, which is what
+lets somebody drag him anywhere in the application rather than around one panel.
+Where they put him outranks where the next step would have placed him.
+
+## How they see it: `present`
+
+`present='window'` (the default) gives the app a real window on their screen —
+once it is shown; see `show` below. Their pointer, their keyboard, their
+cursor, at whatever rate it composites.
+Nothing is translating anything, so nothing can translate it wrongly. A guided
+tour requires one: it draws its instruction and its ring inside the app the
+person is using.
+
+`present='machine'` runs the app on a guest machine of its own, with this
+Issue's worktree mounted in.
+
+There used to be a third, `mirror`, which hid the window and streamed a
+screencast into a card. It is gone: `present='mirror'` and an
+`app.presentations.mirror` entry are both refused. Omit `present` for a window.
+
+```python
+await api.attach_app(surface='panel', present='window')
+```
+
+The presentations are separate instances. Asking for one never hands you the
+process another session is using — the presentation is part of the launch's
+identity, the same way the environment is.
+
+`app.present` in `widgex.yml` moves the default, and `app.presentations` says
+what each one needs in the environment:
+
+```yaml
+app:
+  present: window
+  presentations:
+    window: {}
+```
+
+## Whether they can see it: `show`
+
+**The window starts hidden.** Attaching never puts it over their editor or
+takes their keyboard, because most attaches are you checking something for
+yourself, and a window that jumps in front of somebody mid-sentence is worse
+than one they have to ask for. You can drive it, read it and screenshot it
+while it is hidden.
+
+It comes up when a person is meant to look at it. That is either of two things:
+
+- **You say so when you attach.** `show=True` brings it up straight away. Use
+  it when you attached in order to show them something.
+  `preparing='…'` announces a demo, so it implies `show=True` unless you also
+  pass `show=False`.
+- **You ask them something about it.** These bring the window up by
+  themselves, once, when they ask:
+  - the first `instruct` of a tour;
+  - `request_operator_action`;
+  - `phase_complete`, for an app the lead attached.
+
+  So a check that ends in one of these needs no `show` at all.
+
+A preview started from the panel's own button is shown, since a person pressed
+it. "Show me the app" on a chat row brings it up again at any time.
+
+```python
+await api.attach_app(surface='panel')               # for yourself: stays hidden
+await api.attach_app(surface='panel', show=True)    # to show them: comes up now
+```
+
+Leave `show` off for anything nobody is watching: a check you are running on
+your own, a build you are verifying, a loop of attaches. `cold-attach-runs.ps1`
+and `drive-attach-check.mjs` never show anything; they launch through the
+instance registry, not through this call.
+
+### What "shown" means on each platform
+
+- **macOS** — the window covers the display WidgeX is on, in WidgeX's Space,
+  above the menu bar, and takes the keyboard. That is the only way to be in
+  front of a full-screen WidgeX.
+- **Windows and Linux** — an ordinary window over WidgeX's own rectangle, on
+  WidgeX's display. It is on top for under a second, so it actually comes
+  in front, and then it is not. Clicking WidgeX, Alt-Tab and the taskbar work
+  the way they do for any window. It never covers the whole screen.
+
+Either way it is put back on a real display, so a window that last closed on a
+monitor that is no longer there does not come up off-screen (which looks like a
+white or missing window).
+
+### The ways out
+
+Each still works on a shown preview:
+
+- **"Back to WidgeX · or press Esc twice"**, the tab at the top of the app.
+  Both are handled inside the app, so they work even after the editor that
+  attached it has reloaded.
+- **WidgeX's own button over the preview**, on macOS. The app cannot cover it.
+
+Showing the window does not change what you are driving, and putting it away
+does not detach you. The preview is hidden again and you carry on.
+
+## Permission
+
+Gated, because `build` and `exec` are commands and `widgex.yml` is a file like
+any other — it can arrive on a branch or in a pull request. This is `api.bash`
+with extra steps and it asks the same way.
+
+`api.attach_ide_surface` is gated too, and was not always. That was defensible
+while it launched from a spec hardcoded in WidgeX's own source: the command came
+from us. It reads `widgex.yml` now, so it runs what a branch says to run, and
+the distinction stopped being real.
+
+## One at a time
+
+One instance per workspace and launch. A second session asking for the same app
+waits for the lease rather than starting a second copy — the same rule as
+browser tabs, for the same reason: two drivers on one surface produce confident
+conclusions about a thing neither was looking at.
+
+## It can act
+
+`can_act` comes back True. Nothing here is drawing the conversation you are
+having — it is a throwaway instance, which is exactly what an agent should be
+allowed to click.
+
+(Attaching to WidgeX's own dashboard was once observable-only, for the good
+reason that a misresolved click could close the view you were being watched
+through. That stopped applying when the surface became a separate instance
+rather than the window the user is sitting in front of.)
+
+## Returns
+
+`{status, title, url, port, kind, can_act, environment, isolated, presentation, shown}`
+
+Read `title` and `url`. They name the window it chose, which is the one thing
+worth checking before you believe anything else you observe.
+
+Read `shown` before you say anything to the user about what they can see. It
+is the window's own answer: visible, not minimised, and on a display.
+
+- `True` — it is in front of them. Do not tell them to go and open it.
+- `False` — nobody can see it. That is the normal result without `show=True`,
+  and a `note` says so. With `show=True` you also get `shown_reason`, saying
+  why it did not come up. Pass that on rather than saying "it's open".
+- `None` — nothing could be asked (a guest machine, or an app whose main
+  process cannot be reached). Do not claim either way.
+
+`presentation` says what kind of window it is. It does not say whether the
+window is on screen. Under `machine` there is nothing on their screen until
+you ask for a card.
+
+Then read `environment` and `isolated`, which name the *machine*. `environment`
+is the name you passed, or `None` when you passed nothing; `isolated` says
+whether the instance actually got a home of its own. They are not the same
+question — an environment may declare `home: inherit` — which is why both are
+returned rather than one.
+
+`{'environment': None, 'isolated': False}` means the app is running as you, with
+your home and your credentials, on your checkout. That is the default and it is
+often what you want; it is never what you want when you are testing a first run.
+
+With `reach=`, a `prelude` key rides along: `{replayed, of, ms, reached}`, plus
+`stopped_at`, `wanted`, `outcome` and `saw` when it did not arrive. You do not
+have to check `reached` — a route that stopped has already raised by the time
+you hold this dict.
+
+## See also
+
+- `api.attach_ide_surface(surface)` — the older spelling of
+  `attach_app(surface=…)`. Same code path; prefer this one.
+- `api.drive(url, why)` — a web page, including a dev server
+- `api.phase_complete(...)` — ask for the phase's review once the app shows it
+- `api.request_operator_action(...)` — hand the running app to the user for a step that is theirs

package/python/xactor/man/attach_ide.md

@@ -0,0 +1,65 @@
+<!-- also: self, support, sprite -->
+<!-- group: Working on a website -->
+
+# api.attach_ide(surface='workbench') -> dict
+
+The Support Sprite starts attached to `column`; pass a surface to move.
+
+Drive the WidgeX window this session lives in — the one the user is sitting
+at. **Support Sprite only**: any other session is refused, and should use
+`attach_app`, which starts a separate copy nobody is using.
+
+Nothing is launched. The running IDE already listens on a debugging port, and
+this attaches to *its own* window on that port, so a ring drawn here is drawn
+in front of the person you are helping, and a click here is a click they see.
+
+## Options
+
+- **`surface`** — which part of the window the page verbs see:
+
+| surface | what it is |
+|---|---|
+| `column` | **the WidgeX column — start here.** The side bar on the left, whatever it is showing: the task sidebar down its left edge (folder picker, Settings cog, Board, Main, Your tasks) and the page beside it — a conversation with its Agent / Files / Source Control / Overview tabs, or a Settings page. |
+| `workbench` | VS Code itself: menus, editor tabs, the status bar, notifications. The column shows here only as an empty frame titled "WidgeX". |
+| `panel` | a WidgeX page in the editor area — the board, or a Settings page someone moved there with Settings → Layout. Absent unless one is open. |
+| `chat` | an agent's chat page, wherever it is drawn — usually the column, or an editor tab opened with "Open in editor". |
+| `lead` | the project conversation (Main), in the column. |
+| `xylon` | the Xylon manager. |
+
+That is the default layout; Settings → Layout can move panels. A panel titled
+"CHAT" on the right, if one is ever showing, is VS Code's own chat — it is not
+part of WidgeX and none of these surfaces is in it.
+
+Each webview is a **separate document**. Attached to `workbench`, the verbs see
+VS Code's chrome and *not* the inside of the column; attached to `column`, the
+reverse. Re-attach to move between them — it is cheap.
+
+## Returns
+
+`{"status": "attached", "surface": ..., "url": ...}`, or `{"error": "…"}`:
+
+| what `error` says | what to do |
+|---|---|
+| `no debugging port` | WidgeX was started without one. Tell the user; it needs a restart after WidgeX adds it. |
+| `… is not open in this window` | open it first from the column — the Settings cog, Board, or a task in Your tasks — then attach again. |
+
+## Examples
+
+Walking someone to their models:
+
+```python
+await api.attach_ide("column")
+await api.instruct("Click the Settings cog, at the top of the task sidebar.",
+                   api.find(role="button", text_exact="Settings"))
+r = await api.await_user(api.find(role="button", text_exact="Settings"))
+
+await api.instruct("Now Model configuration, in the Settings list.",
+                   api.find(role="tab", text_exact="Model configuration"))
+```
+
+Prefer this to a palette command: most "WidgeX: …" commands predate the
+column and do not land where the feature lives now.
+
+## See also
+
+`highlight`, `instruct`, `await_user`, `attach_app`, `driving`

package/python/xactor/man/attach_ide_surface.md

@@ -0,0 +1,31 @@
+# api.attach_ide_surface(surface='panel') -> dict
+<!-- also: ide-surface, dashboard, panel-surface, drive-the-ide -->
+<!-- group: Working on a website -->
+
+**The older spelling of `api.attach_app(surface=…)`.** Use that one — see
+`api.man('attach_app')`. This name is kept because sessions and notes from
+before the rename still use it; there is no second code path behind it.
+
+It does what `attach_app` does: starts a **separate copy** of WidgeX from the
+workspace's `widgex.yml` and attaches to the named surface in it. It does not
+attach to the window the user is working in — only the Support Sprite does
+that, with `attach_ide`.
+
+What it used to say no longer holds: the surface is **not** read-only. The copy
+is a throwaway nobody else is using, so the page verbs act on it like any other
+page.
+
+## Options
+
+- **`surface`** — a name from `app.surfaces` in `widgex.yml`; defaults to
+  `"panel"`. In WidgeX's own: `panel` is the dashboard (an editor tab in the
+  middle of the window), `chat` is an agent's chat page (usually drawn in the
+  WidgeX column on the left), `column` is that column whatever it shows.
+
+## Returns
+
+The same as `attach_app`.
+
+## See also
+
+`attach_app`, `request_operator_action`