@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/bulletin.md

@@ -0,0 +1,88 @@
+# The local bulletin
+<!-- group: Concepts -->
+
+A board this machine keeps per repository, carrying every agent's task list.
+
+Agents working the same codebase used to be invisible to each other. Two of
+them given adjacent work would refactor the same file in opposite directions,
+and neither ever learned why its edits kept coming back changed. The board is
+the cheapest fix that does not require them to coordinate: everyone posts what
+they are doing, anyone can read it, and nobody is obliged to.
+
+## What is on it
+
+One block per agent, carrying that agent's current task list:
+
+```
+AGENT N1 ACTIVE WORK:
+  1. [x] Read XylonMountConfig for the file-watch shape
+  2. [~] Wire the bulletin store into setSessionTodos
+  3. [ ] Add api.read_bulletin and api.wait_for_task
+```
+
+The list is exactly what that agent last sent to `todo_write` — or to the
+native `TodoWrite` tool, which posts to the same place. Marking a task complete
+updates the board; completing the last one takes the agent off it.
+
+## How you get on and off
+
+You go **on** the first time you publish a list with anything unfinished. You
+come **off** when every task is `completed`, or when your session ends.
+
+So an agent that is not on the board is not necessarily idle — it may simply
+never have published a list. Absence is not evidence, in either direction.
+
+## Its reach
+
+Per **repository**, per **machine**. Two IDE windows open on the same repo see
+each other; two different projects do not.
+
+A forked session works in a clone of the repo, but it posts to the **origin's**
+board rather than its clone's — otherwise the one agent most likely to collide
+with you would be the one you could not see.
+
+## Reading it
+
+`api.read_bulletin()` returns the whole board as text. `api.wait_for_task(node,
+n)` blocks until another agent's task number `n` completes, and
+`api.wait_for_task(node)` until its whole list is done.
+
+Your session's system prompt says how many other agents were on the board when
+you started. That number is a snapshot; the board itself is always current.
+
+## It is a hint, not a lock
+
+Nothing here reserves a file, blocks a write, or fails a call. It exists so you
+can notice a collision before it happens rather than after. There is no way to
+claim anything and no way to stop anyone.
+
+That is deliberate. A lock between agents needs a story for the agent that took
+one and died, and this is not worth one.
+
+## Getting it wrong
+
+**Treating it as a lock.** Two agents can edit one file at the same moment and
+the board will not stop them. What it gives you is the chance to say "someone
+is already inside this" before you start.
+
+**Waiting on each other.** Two agents can `wait_for_task` on each other and both
+sit until their timeouts. Nothing detects it — the bounded timeout is the only
+thing that ends it, and the answer is not to wait for work you could do
+yourself.
+
+**Expecting a subagent to appear.** `agent` runs a subagent, not a session.
+It cannot publish a task list, so the board shows *sessions*, and a busy
+subagent shows up as its parent's entry or not at all.
+
+**Believing a stale entry.** A window that crashed leaves its agents up until
+they are reaped. They are checked against the process that wrote them, so this
+resolves in seconds rather than minutes — but an agent that has published
+nothing for a while is annotated with when it was last seen, and that is worth
+reading.
+
+**Never publishing.** If you do not call `todo_write`, nobody can see what you
+are doing. That costs the other agents more than it costs you.
+
+## See also
+
+`read_bulletin`, `wait_for_task`, `todo_write`, `relay`, `sessions`

package/python/xactor/man/capture_page.md

@@ -0,0 +1,54 @@
+# api.capture_page(path, dispatcher_id, session_id) -> dict
+<!-- group: Working on a website -->
+
+Freezes the driven page — scripts stripped, styles inlined — and writes it straight to `path`. Gated.
+
+This is how a benchmark's fixture gets made, not a general-purpose save. A
+frozen page has no script left to phone home or re-render itself, and its
+styles are inlined so it renders the same offline as it did live. The write
+happens host-side, not in your process: the page is reached over CDP, which
+has no filesystem of its own, and a frozen document can run to megabytes —
+round-tripping that much text back to you as a return value would be the
+expensive way to do what a direct write does for free.
+
+It is gated for the same reason `browser_snapshot` is: the frozen page is
+whatever the human happens to be signed into, and writing that to disk is a
+second reason on top of the first.
+
+## Options
+
+- **`path`** — where to write the freeze, relative to the workspace root or
+  absolute. Parent directories are created as needed.
+- **`dispatcher_id`** — the browser dispatcher to capture.
+- **`session_id`** — used to find the dispatcher when `dispatcher_id` is
+  unknown. Usually left out; your own session's dispatcher is used.
+
+## Returns
+
+`{path, url, title, nodes}` — never the frozen page itself. `nodes` is the
+addressable-element count, which is what tells you the capture actually saw a
+real page rather than a blank one.
+
+## Examples
+
+```python
+await api.drive("https://example.com/pricing", why="freeze the pricing page")
+await api.capture_page(".widgex/benchmarks/upgrade-plan/captures/1/pricing.json")
+```
+
+## Getting it wrong
+
+**Reaching for this to save a screenshot.** `browser_screenshot` is the
+picture; this is a structural freeze meant to be replayed, not looked at.
+
+**Calling it before the page is where you mean it to be.** It captures
+whatever is currently on screen — settle the page first (`api.wait_stable()`
+or an explicit check) or you freeze a transition instead of a state.
+
+**Using it outside a benchmark's own directory.** It writes anywhere `path`
+names; nothing enforces `.widgex/benchmarks/`. That is deliberate — the
+convention is yours to keep, not the call's to enforce.
+
+## See also
+
+`browser_snapshot`, `browser_screenshot`, `drive`

package/python/xactor/man/cd.md

@@ -0,0 +1,64 @@
+# api.cd(path) -> str
+<!-- group: Coding -->
+
+Move the shell's working directory. Persists across execs. Not gated.
+
+## Options
+
+- **`path`** — the new directory. Absolute, or relative to the *current* cwd.
+  `".."` works.
+
+## Returns
+
+- `"Changed to {resolved_absolute_path}"` on success.
+- `"Error: not a directory: {path}"` if the path is missing or is a file.
+  **This is a return, not a raise** — the cwd is unchanged and nothing tells
+  you unless you look.
+
+## What it affects
+
+The new cwd is used by every subsequent relative path in the session, in this
+exec and in every later one:
+
+- `read_file`, `write_file`, `edit_file`, `ls`, `cd`
+- the default `path` for `glob` and `grep`
+- **the working directory `api.bash` runs commands in**
+
+It does not affect anything outside the shell. The session's repo, the xylon
+node and the browser are all unmoved.
+
+## Examples
+
+```python
+return await api.cd("widgex-ide/extension")
+```
+
+Check it landed:
+
+```python
+r = await api.cd(target)
+if r.startswith("Error:"):
+    return r
+return await api.bash("pwd")
+```
+
+## Getting it wrong
+
+**Ignoring the error return.** A failed `cd` leaves you in the old directory,
+so the next twenty relative paths quietly resolve somewhere else. This is the
+one thing that actually goes wrong with this call.
+
+**Using it as a scope.** There is no "cd back" — it is a persistent change to
+the whole session, not a block. If you need one command elsewhere, prefer
+`api.bash("cd sub && ...")`, which is scoped to that command, or pass an
+explicit `path=` to the call that needs it.
+
+**Assuming it moves `api.bash`'s idea of `~` or `$PWD` for already-running
+work.** It sets the cwd for commands started *after* it.
+
+**Preferring it to absolute paths.** Most of the time an absolute path in the
+one call that needs it is clearer and cannot leak into later execs.
+
+## See also
+
+`bash`, `ls`, `glob`, `read_file`

package/python/xactor/man/chess_move.md

@@ -0,0 +1,53 @@
+# api.chess_move(piece, to, promotion=None) -> dict
+<!-- group: Sessions -->
+<!-- also: chess_state, chess -->
+
+Play your move as Black in the user's `/chess` game. Never asks. Only while
+the user has a game open with you in wgx, the terminal app; anywhere else both
+calls are refused.
+
+The user plays White on a board beside your chat. When they move you are told,
+the way relay mail reaches you: at the end of a tool result if you are mid-turn,
+or as a prompt if you are idle. Then it is your move.
+
+## Squares
+
+`(row, col)`, each 0-7. Row 0 is White's back rank (rank 1) and row 7 is
+yours (rank 8); col 0 is the a-file. So e7 is `(6, 4)` and e5 is `(4, 4)`. A
+name like `"e7"` works anywhere a square does.
+
+## api.chess_state() -> list
+
+Every piece on the board as a `(piece, row, col)` tuple, the piece named with
+its colour: `B` is Black (you), `W` is White.
+
+```python
+[("RookW", 0, 0), ("KnightW", 0, 1), …, ("PawnB", 6, 4), …, ("KingB", 7, 4), …]
+```
+
+## api.chess_move(piece, to, promotion=None)
+
+- `piece` — the square of the Black piece to move, or a tuple straight out of
+  `chess_state()`. Given a tuple, the name is checked against the square.
+- `to` — where it goes.
+- `promotion` — `"Q"`, `"R"`, `"B"` or `"N"` for a pawn reaching row 0. A
+  Queen when omitted.
+
+Castle by moving the King two squares: `chess_move("e8", "g8")`. En passant is
+the pawn's diagonal step onto the empty square behind the pawn that just
+double-stepped.
+
+Returns `{ ok, move, check, over, status }`, where `move` is the move in long
+algebraic (`Ng8-f6`, `e7xd6 e.p.`, `O-O`, `+` for check, `#` for mate).
+
+**An illegal move raises**, saying why — no piece there, not yours, not how it
+moves, leaves your King in check, not your turn, the game is over — and the
+board is unchanged. Read the board again and choose another.
+
+## Example
+
+```python
+board = await api.chess_state()
+pawn = next(p for p in board if p == ("PawnB", 6, 4))
+return await api.chess_move(pawn, (4, 4))      # e7-e5
+```

package/python/xactor/man/children.md

@@ -0,0 +1,89 @@
+# api.children() -> list[dict]
+
+<!-- group: Sessions -->
+
+What you have running underneath you, right now. Never asks.
+
+The session tree cannot answer this. `xylon_get_tree()` is a record of what
+happened — every node, live and long finished, across every project — and this is
+a question about what is happening. Filtering one to get the other is how a
+session ends up reporting confidently that it has nothing running.
+
+## Returns
+
+One dict per child:
+
+```python
+{"kind": "delegate" | "extend" | "branch",
+ "id": str, "node": str | None, "sessionId": str | None,
+ "label": str, "status": str, "model": str | None, "branch": str | None,
+ "task": str | None, "startedAt": int | None,
+ "ahead": int, "dirty": int, "files": int}
+```
+
+- **`kind='delegate'`** — an `agent(wait=True)` running in your shell. Always
+  `working`: one that has finished is gone from this list, because it no longer
+  exists anywhere. `node` and `sessionId` are null — it is not a session. `task`
+  is the opening line of what you asked it for.
+- **`kind='extend'`** — a session sharing your directory.
+- **`kind='issue'`** — an Issue you raised with `agent(raise_=True)`. Here
+  because you started it, not because it is underneath you: it stands beside
+  your work in the Issue list, and the user lands and retires it on its own
+  terms. It does not disappear when you do.
+- **`kind='branch'`** — a session on a worktree and branch of its own.
+  `ahead`/`dirty`/`files` count what it has done since it started; all three are
+  zero for the other kinds.
+
+## Only one level
+
+Your children, not theirs. A grandchild is its parent's business, and a flat list
+mixing the two would make "how many do I have" ambiguous at exactly the moment
+you are asking it. Reach further by asking a child through its own session.
+
+## What it does not tell you
+
+What a child **said**. That is `session_join`, and for one still running it would
+be half a turn. This answers what is true, not what was reported.
+
+## Examples
+
+Answering the question directly:
+
+```python
+kids = await api.children()
+if not kids:
+    return "Nothing running."
+return "\n".join(f"{c['kind']} {c['label']} — {c['status']}" for c in kids)
+```
+
+Waiting for whatever is still going:
+
+```python
+for c in await api.children():
+    if c["sessionId"]:
+        await api.session_join(c["sessionId"], timeout=600)
+```
+
+Reporting what is ready for the user to merge:
+
+```python
+ready = [c for c in await api.children()
+         if c["kind"] == "branch" and (c["files"] or c["dirty"])]
+return f"{len(ready)} ready to merge: " + ", ".join(c["branch"] for c in ready)
+```
+
+## Getting it wrong
+
+**Polling it in a loop.** It is cheap, but nothing changes between two reads a
+second apart. `session_join` blocks properly.
+
+**Reading `ahead` as "ready".** A branch agent with `ahead=0` and `dirty=4` has
+done four files' worth of work and committed none of it, which still lands. The
+count that answers "has it done anything" is `files`.
+
+**Expecting a finished delegate.** They are forgotten on return. If you needed
+its answer you already have it — `agent(wait=True)` gave it to you.
+
+## See also
+
+`agent`, `session_join`, `sessions`, `xylon`

package/python/xactor/man/close_task.md

@@ -0,0 +1,14 @@
+# api.close_task(task) -> dict
+
+<!-- group: Sessions -->
+
+Close a task. Only when the user asks for it.
+
+With nothing unlanded, the task closes: its agents end, its worktree and branch
+are removed. With unlanded work, the user is shown the choice — land it, keep
+the branch, or discard it — and this returns straight away with
+`{"asked": True}`. You never throw work away.
+
+## Returns
+
+`{"closed": bool, "asked": bool, "why": str | None}`

package/python/xactor/man/compact.md

@@ -0,0 +1,75 @@
+# api.compact(rundown, next_step=None) -> dict
+<!-- also: compaction, context, clear_context, rundown, context-window -->
+<!-- group: Sessions -->
+
+Clear your own context at a point you choose, keeping a brief rundown. Not gated.
+
+A long conversation costs more with every turn, because every turn re-reads all
+of it. WidgeX compacts at the share of the model's context window the user set
+on Settings → Routing (33% unless they changed it); the terminal tool's
+description gives the figure. Between turns WidgeX compacts by itself. Mid-turn
+it cannot, so once its estimate of your context passes the line, one of your
+tool results ends with a **context check**, naming the line, that asks you to
+call this at the next convenient point.
+
+## What happens
+
+1. The call records your rundown and returns at once.
+2. You finish the step you are on and **end your turn**.
+3. The conversation continues in a fresh context holding:
+   - the WidgeX system prompt,
+   - your rundown,
+   - the last few lines of the conversation,
+   - a note on where the rest is.
+4. If you gave `next_step`, the fresh context starts on it straight away.
+   Otherwise nothing more runs until the next prompt.
+
+Nothing is lost. The whole transcript stays on your node:
+
+- `xylon_read_turns(".", offset=…)` pages through the prompts and replies.
+- `xylon_search("words")` finds the turn where something was said.
+- `xylon_read_messages(".")` returns everything, tool output included.
+
+## Arguments
+
+- **`rundown`**: 5 to 10 short lines on where things stand: what was asked,
+  what is done or decided, what is in hand, and what is next. Name files and
+  functions, but do not paste code: the fresh context can read the files
+  itself. At most 4000 characters.
+- **`next_step`**: the prompt the fresh context starts on, written to yourself
+  ("Run the extension tests and fix what fails"). Leave it out when the work is
+  finished and you are waiting on the user.
+
+Returns `{"status": "scheduled", "message": …}`. Raises when the rundown is
+empty or too long.
+
+## Example
+
+```python
+return await api.compact(
+    "User asked for the export button to write CSV as well as JSON.\n"
+    "Done: exportCsv() in src/export/csv.ts, wired into ExportMenu.tsx.\n"
+    "Decided: quote every field, CRLF line endings (Excel).\n"
+    "In hand: test/export.test.mjs has two failing cases for embedded quotes.\n"
+    "Next: fix the quoting in exportCsv and rerun that file.",
+    next_step="Fix the embedded-quote cases in exportCsv and rerun test/export.test.mjs.",
+)
+```
+
+## Getting it wrong
+
+**Compacting in the middle of an edit.** The fresh context only knows what the
+rundown and the last few lines say. Finish the edit, or at least the file, first.
+
+**A rundown that is a summary.** Ten paragraphs spend the space this frees.
+Write where things stand; the transcript has the rest.
+
+**Carrying on after the call.** The compaction happens when your turn ends.
+Work done after it is in the context being cleared, and only the last few lines
+of it survive.
+
+**Asking the user to repeat themselves afterwards.** Read the transcript instead.
+
+## See also
+
+`xylon_search`, `xylon_read`, `xylon_blame`

package/python/xactor/man/drive.md

@@ -0,0 +1,140 @@
+# api.drive(url, why, new_tab=False) -> dict
+<!-- group: Working on a website -->
+
+Drive a site by hand, with no widget. Gated.
+
+The exception, not the default. Use it when `api.widgets()` has nothing for the
+site. Every action is then a raw L1 call against whatever the page happens to
+look like, so `why` is the only record of intent there will be — and it is what
+the user sees when deciding whether to allow it.
+
+It is also how you look at a page you have just written. `file://` is an
+accepted scheme and a dev server is an ordinary `http://` URL, so drive then
+`browser_screenshot` and you can see what you made instead of reasoning about
+clip-path coordinates in your head.
+
+## Options
+
+- **`url`** — where to go. One of:
+  - `https://` or `http://` — any host, including `http://localhost:5173/` and
+    `http://127.0.0.1:8080/`. A dev server needs nothing special.
+  - `file://` — a page on disk.
+  - an **absolute** path, which becomes its `file://` URL for you. Relative
+    paths are refused: `docs/index.html` and a bare hostname are the same
+    string.
+
+  Anything else — `data:`, `javascript:`, `chrome://`, `about:blank`, a bare
+  domain — raises before the prompt. Those are ways of making a page run
+  something, or the browser's own furniture, rather than places to go.
+- **`why`** — **required.** What you are there to do, in one line. An empty
+  string raises with the reason: on a site nothing models, nothing else can
+  tell. A page on your own disk is no more self-explaining than one on the web.
+- **`new_tab`** — `False` by default: you have one tab, and each drive moves it
+  to the new address. Pass `True` to open the page beside the one you are on
+  instead, when you genuinely need both. Opening tabs is deliberate, never a
+  habit: every one lands in the user's tab strip.
+
+## Your tab, and the user's
+
+You work in the background. Your tab opens behind whatever the user is doing
+and is never brought in front of them; they can look at it whenever they like,
+and looking does not take it from you.
+
+- **They worked in it** — clicked, scrolled or typed in the page — so it is
+  theirs. Your next drive somewhere else opens a new tab and leaves theirs
+  where they left it. Picking the tab in the strip just to look does not count.
+- **You need them** — a form to submit, a sign-in, a CAPTCHA: fill in what you
+  can, then `api.request_operator_action(action, detail)`. That hands them this
+  tab; their card has an Open button that brings it up exactly as you left it.
+  You will not navigate a handed tab again — your next drive opens a new one
+  beside it — and it stays open after you finish, so the card still works.
+
+A browser specialist you hand work to gets one tab of its own, so several
+running at once do not drive each other's pages.
+
+A `file://` target that does not exist raises `FileNotFoundError` **before** the
+permission prompt, rather than costing you a tab and a screenshot of Chromium's
+error page.
+
+## Returns
+
+```python
+{"url": str, "state": str, "why": str}
+```
+
+`state` is `"UnknownPage"` unless a loaded widget happened to match.
+
+## Examples
+
+A site with no model:
+
+```python
+return await api.drive(
+    "https://status.example.com/incidents/4821",
+    why="read the incident timeline the user linked, to date the outage",
+)
+```
+
+Looking at markup you have just written:
+
+```python
+out = f"{api.cwd}/.widgex-scratch/animation.html"
+await api.write_file(out, html)
+await api.drive(out, why="check the panel's entry animation before shipping it")
+shot = await api.browser_screenshot()
+```
+
+A dev server, which was never a special case:
+
+```python
+await api.drive("http://localhost:5173/settings", why="confirm the new tab renders")
+```
+
+Falling back only after checking:
+
+```python
+found = await api.widgets(url)
+if any(w["matches"] for w in found):
+    return await api.use_widget(next(w["name"] for w in found if w["matches"]))
+return await api.drive(url, why="download the CSV export the user asked for")
+```
+
+Then working the page, with the verbs in this shell — see `driving`:
+
+```python
+print(await api.outline())                        # the shape of the page
+hits = await api.search(role="button", like="export")
+api.click(api.find(role="button", like="export"))
+print(await api.drain())
+```
+
+## Getting it wrong
+
+**Using it when a widget exists.** `api.widgets()` costs nothing. Driving past a
+model throws away tested transitions and shows the user an anonymous click.
+
+**A vague `why`.** "look at a page" is the whole explanation the user gets for
+an unmodelled site. Say what you are there to do.
+
+**Passing a bare domain.** No scheme, no call — it raises before prompting.
+`example.com` is indistinguishable from a relative path, so neither is guessed.
+
+**Standing up a web server to show yourself one file.** That was the only route
+before `file://` was accepted, and it is three steps you no longer need. Write
+the file, drive its path.
+
+**Reading the CSS instead of looking at the page.** The reason this capability
+exists: a screenshot shows an animation is wrong in ways the source does not.
+
+**Expecting `state` to be useful.** It is `UnknownPage` in the normal case.
+There is no state machine here; that is what "no widget" means.
+
+**Driving the same site repeatedly.** That site wants a widget. Say so.
+
+**Using a screenshot to locate elements.** An image cannot be searched.
+`browser_hybrid` returns structure.
+
+## See also
+
+`driving`, `widgets`, `use_widget`, `widget-model`, `browser_hybrid`,
+`browser_screenshot`

package/python/xactor/man/drive_space.md

@@ -0,0 +1,72 @@
+# api.drive_tree / drive_import / drive_push / drive_review — drive spaces
+<!-- also: drive_tree, drive_import, drive_push, drive_review, drive_review_status, drive_spaces, onedrive, google_drive, gdrive -->
+<!-- group: Coding -->
+
+A **drive space** is a OneDrive or Google Drive folder opened as the workspace.
+The person using it is usually not a developer and never sees git. What matters
+to them is their documents, and what reaches their drive.
+
+These calls exist only in a drive space, or in a task cut from one. Anywhere
+else they say so and do nothing.
+
+## Two places to stand
+
+**In the space itself** (the Coordinator, or any main agent) you have the
+folder's *listing* and none of its bytes. Your system prompt carries the listing
+as it was when your session started. Files arrive when you import them.
+
+```python
+await api.drive_tree("Reports", depth=1)        # what is there now
+await api.drive_import("Reports/Q3.docx")       # fetch it, to the same path
+# ... edit Reports/Q3.docx with python-docx ...
+await api.drive_push(["Reports/Q3.docx"], "Updated the Q3 totals")
+return "Asked you to approve the Q3 report changes."
+```
+
+**In a task** you have a full copy of one sub-folder, chosen by the user when
+the task started. Edit freely, then ask for review once:
+
+```python
+await api.drive_review("Rewrote the summary and fixed the tables")
+return "Your changes are open for review in the browser tabs."
+```
+
+## Nothing reaches the drive without approval
+
+`drive_push` and `drive_review` **do not block and publish nothing by
+themselves.** Each changed file opens in its own browser tab, rendered — a PDF as
+pages, a Word document as a document — with "Approve all & publish" and "Request
+changes" on every tab.
+
+- **Approve** publishes the whole set and **overwrites** the drive's copies. A
+  task's changes are committed first. The overwritten versions stay in the
+  drive's own version history.
+- **Request changes** publishes nothing and sends you the user's note as a new
+  message.
+
+Either way you are told in your own conversation. So the call is the **end** of
+a turn: say what you are waiting on and stop. `drive_review_status(review_id,
+wait_seconds)` exists for checking, not for polling.
+
+## The calls
+
+- `drive_tree(path='', depth=None) -> {drive, folder, rows, text}` — the listing
+  now. Rows carry `folder`, `size`, `readOnly` and `imported`. Not gated.
+- `drive_import(paths) -> {imported, kept, skipped}` — one path or a list, file or
+  folder. A file you imported and since edited is **kept**, not overwritten.
+  Gated: it downloads and writes files.
+- `drive_push(paths, message=None) -> {review_id, files, state}` — from the space.
+- `drive_review(message=None) -> {review_id, files, state}` — from a task.
+- `drive_review_status(review_id, wait_seconds=0)` — `open`, `publishing`,
+  `approved`, `rejected` or `failed`, with what was published or refused.
+
+## Getting it wrong
+
+**Polling after asking.** You are told. Ending the turn is the right move.
+
+**Writing to an exported Google document.** Docs, Sheets and Slides arrive as
+`.docx`, `.xlsx` and `.pptx` exports marked read-only. They can be read; a push
+of one is refused by name and the rest of the set still publishes.
+
+**Importing a whole folder to edit one file.** Import the file. A task is the
+tool for working across a folder — it gets the whole thing.