fix(docs): clarify released CLI and source-preview setup

README.md

@@ -7,12 +7,14 @@ A tiny coding agent with a shared thread. Its native terminal client and browser
 ```sh
 tress setup              # connect to a host; no personal API key needed
 tress                    # join your saved thread
-tress attach -s <id> --chat-only  # join another thread on that host
+tress attach -s <id>      # join another thread on that host
 ```
 
-[Install and configuration guide](docs/setup.md). Use v0.3.0 or newer for connected
-folders and environment-based startup. The v0.1.0 binary requires an explicit
-URL with `tress attach`.
+[Install and configuration guide](docs/setup.md). Published v0.3.0 supports
+chat attachment, `tress connect` for paired folders, and environment-based
+startup. Combined `attach` file sharing (`--root`, `--allow-write`, and
+`--chat-only`) is a **source preview**: build this checkout before using those
+options below. The installer currently downloads v0.3.0.
 
 **Existing assistant-ui applications:** the [source preview](examples/existing-app/README.md)
 connects the browser and terminal to your server-owned Harness thread, with

docs/connected-folder.md

@@ -1,5 +1,10 @@
 # Connect a computer or VM workspace
 
+**Source preview:** combined `attach` file sharing below requires a CLI built
+from this checkout. The installer currently provides v0.3.0, where `attach`
+joins chat and `tress connect --site <url> --root .` shares a folder from a
+separate terminal. See [installation and release compatibility](setup.md#install).
+
 The site owns the model credentials and, in managed mode, the Harness credentials. `tress attach` does
 not log into Harness, need an API key, or open an inbound port. It offers a filesystem
 to one browser-owned demo thread through a short-lived pairing code.

docs/setup.md

@@ -16,11 +16,13 @@ curl -fsSL https://tress-theta.vercel.app/tress.sh | sh
 The installer downloads a binary, verifies its checksum, and installs to
 `~/.local/bin`. Follow its PATH instructions if needed.
 
-Use **v0.3.0 or newer** for connected folders, automatic local startup, and
+Published **v0.3.0** supports paired folders through `tress connect`, automatic local startup, and
 the `TRESS_HOST` / `TRESS_SESSION` environment shortcuts. Hosted setup and
 complete `tress ask` replies remain supported.
-Check `tress --version` after installation. To build the current checkout
-with Rust instead:
+Check `tress --version` after installation. Combined `attach` file sharing
+(`--root`, `--allow-write`, and `--chat-only`) and existing Harness app support
+are **source previews**, not included in that release. For these workflows,
+build the current checkout with Rust from the repository root:
 
 ```sh
 cargo install --locked --path crates/tress
@@ -33,7 +35,7 @@ replaces the executable and leaves your configuration and files untouched.
 
 The default changes in v0.2.0: `tress` and `tress ask` connect to a host. Run
 `tress setup` once to choose that host and session. Existing commands using
-`tress attach <url> -s <id>` work without setup. In the updated CLI,
+`tress attach <url> -s <id>` work without setup. In the source-preview CLI,
 attaching to a Tress site session offers the machine filesystem for browser
 pairing by default; add `--chat-only` to retain chat-only behavior.
 
@@ -70,7 +72,7 @@ Then use:
 tress                           # join the saved thread
 tress --ui                      # opt into the full terminal interface
 tress ask "explain these files"  # send a hosted prompt and exit
-tress attach -s <session-id> --chat-only  # another thread on the saved host
+tress attach -s <session-id>     # another thread on the saved host
 ```
 
 Explicit attachment still works without setup:
@@ -79,7 +81,7 @@ Explicit attachment still works without setup:
 tress attach https://your-tress-host.example -s <session-id>
 ```
 
-With a Tress site session, attach shares the machine filesystem by default
+In the source preview, with a Tress site session, attach shares the machine filesystem by default
 (`/` on macOS/Linux, the current drive root on Windows). Enter its pairing code
 in the browser chat to activate access. To restrict it to a project folder:
 
@@ -90,7 +92,14 @@ tress attach https://your-tress-host.example -s <session-id> --root . --ui
 Add `--chat-only` to join without sharing files, or `--allow-write` for edits. Exit to stop sharing. See the
 [connected folder guide](connected-folder.md) for access rules and remote VMs.
 This requires the updated Tress site's connection API; the older `connect`
-command remains supported for a folder-only process.
+command remains supported for a folder-only process. With published v0.3.0,
+run this in a separate terminal and enter its pairing code in the browser:
+
+```sh
+tress connect --site https://your-tress-host.example --root .
+```
+
+This shares the current folder read-only. Add `--allow-write` to permit edits.
 
 With `--chat-only`, plain `tress`, or `tress ask`, files belong to the host's workspace, which may be a local directory on that
 host, virtual files, or a sandbox. Connecting from a project directory does not

site/docs/reference.mdx

@@ -17,6 +17,11 @@ description: What this preview supports, and what still needs upstream release w
 | Optional access adapter | `packages/access`, source package; Node 24 or a TypeScript-aware build. Existing host auth can be used directly. |
 | Harness adapters | Upstream source at `c07dab9b1eb32a3800d2bad25e807efa0cfeedef`; several are not published on npm. |
 
+The installer currently provides v0.3.0. Its `attach` joins chat; use the
+separate `connect` command for paired folders. Combined `attach` file sharing
+and the Harness commands below require a source build. See the
+[release and source-preview steps](/docs/try#build-the-source-preview).
+
 The CLI can negotiate the existing Tress host or a Harness host, display the
 active branch's text and tool activity, and submit text to a known thread.
 Harness preloads its recent message window. Full history pagination, generic

site/docs/try.mdx

@@ -22,15 +22,50 @@ holding that command can join the session. The demo validates it internally;
 no external auth service or `createTressAccess` setup is required. A bare host
 address selects its default thread; `-s` selects a Tress demo session.
 
-By default, this offers the terminal machine's whole filesystem, read-only.
+Send a prompt from the terminal. Its response appears in both clients.
+Add `--ui` to use the full terminal interface.
+
+## Share files with the released CLI
+
+The installer currently provides **v0.3.0**. Its `attach` command joins the
+conversation; it does not share your machine's files. In a separate terminal,
+run this from the folder you want to share:
+
+```sh
+tress connect --site https://your-demo.example --root .
+```
+
+Enter its pairing code under **connect folder** in the same browser chat.
+Keep that terminal open while using the files. Access is read-only by default;
+add `--allow-write` for edits. Use `--root /path/to/project` for another folder.
+Closing the connector stops file access while the conversation remains available.
+
+## Build the source preview
+
+Combined chat and file sharing through `attach`, including `--root`,
+`--allow-write`, and `--chat-only`, requires the current source build. These
+options are not in the published v0.3.0 binary. With Rust installed:
+
+```sh
+git clone https://github.com/assistant-ui/tress.git
+cd tress
+cargo install --locked --path crates/tress
+```
+
+If you already have the repository, use its current checkout. Run the binary
+installed by Cargo (`~/.cargo/bin/tress` on macOS/Linux), or put that directory
+before `~/.local/bin` on PATH. Both builds currently report `0.3.0`, so the
+version string alone does not identify the source preview.
+
+With that source build, run the copied `attach` command again. By default,
+it offers the terminal machine's whole filesystem, read-only.
 Enter the printed pairing code under **connect folder** in this browser chat;
 the terminal opens after pairing. Use `--root /path/to/project` to restrict the
 scope, or `--chat-only` to join without offering files. Whole-filesystem access
 includes personal files your terminal can read, subject to OS permissions;
 symlinks and special files remain unavailable.
 
-Send a prompt from the terminal. Its response appears in both clients. Close
-the terminal to stop sharing. Run the command and pair again to resume access.
+Close the terminal to stop sharing. Run the command and pair again to resume access.
 
 ```text
 /status      show connection and host details

site/src/components/LocalConnection.tsx

@@ -34,6 +34,7 @@ export function LocalConnection({
   const [error, setError] = useState("");
   const [expanded, setExpanded] = useState(false);
   const command = `tress attach ${origin || "https://your-tress-site"} -s ${attachId} --ui`;
+  const releasedCommand = `tress connect --site ${origin || "https://your-tress-site"} --root .`;
 
   useEffect(() => {
     let alive = true;
@@ -142,12 +143,22 @@ export function LocalConnection({
       </div>
       {!device && expanded ? (
         <div className="local-connect-steps">
+          <p><strong>Source preview.</strong> This combined file-sharing command requires a <a href="/docs/try#build-the-source-preview">CLI built from source</a>; the installer currently provides v0.3.0.</p>
           <p>Run this on your computer, VM, or remote host. After pairing, it shares the whole filesystem accessible to that terminal and opens this chat. Add <code>--root /path/to/project</code> to restrict access to a folder, or <code>--allow-write</code> to allow edits. Shell execution is not included.</p>
           <div className="attach-command">
             <span aria-hidden="true">$</span>
             <code>{command}</code>
             <CopyButton text={command} label="Copy workspace connection command" compact disabled={!origin} />
           </div>
+          <details>
+            <summary>Using the released v0.3.0 CLI?</summary>
+            <p>Run this in the folder you want to share, in a separate terminal. Enter its pairing code below. Add <code>--allow-write</code> to permit edits.</p>
+            <div className="attach-command">
+              <span aria-hidden="true">$</span>
+              <code>{releasedCommand}</code>
+              <CopyButton text={releasedCommand} label="Copy v0.3.0 folder connection command" compact disabled={!origin} />
+            </div>
+          </details>
           <form onSubmit={(event) => void claim(event)}>
             <label htmlFor="local-pair-code">Pairing code printed by Tress</label>
             <input

site/src/components/Thread.tsx

@@ -434,7 +434,7 @@ export function Thread({
           break;
         case "/files":
           if (hasWorkspace) setShowFiles((visible) => !visible);
-          else setNotice("Run the attach command on your computer or VM, then enter its pairing code under connect folder to browse its files.");
+          else setNotice("Open connect folder for the command to share files from your computer or VM. Combined attach file sharing requires the source-preview CLI.");
           break;
         case "/pwd":
           showWorkspaceInfo();
@@ -629,7 +629,7 @@ export function Thread({
           </div>
           <p>
             Same thread, live in both clients. Add <code>--ui</code> for the
-            full terminal interface. {config?.session ? <>After pairing, the terminal shares its whole filesystem read-only. Add <code>--root /path/to/project</code> to limit the scope, <code>--allow-write</code> for edits, or <code>--chat-only</code> to join without sharing files.</> : null}
+            full terminal interface. {config?.session ? <>The released v0.3.0 CLI joins the chat. Sharing this machine through <code>attach</code> requires the <a href="/docs/try#build-the-source-preview">source-preview CLI</a>.</> : null}
           </p>
         </details>