docs: Add Windows & Projects concept page (#56402)

## Summary

- Adds a new concept page (`docs/src/windows-and-projects.md`)
explaining how Zed handles multiple projects in windows
- Fixes the VS Code migration guide which incorrectly stated "Zed does
not support multi-root workspaces"
- Adds cross-links from Getting Started, CLI Reference, and Parallel
Agents docs

## Context

With multi-workspace now universally enabled, the default behavior is:
- **File > Open** opens projects in the current window's sidebar (not a
new window)
- **Cmd+Enter** in Open Recent opens in a new window
- **CLI `-n` flag** forces a new window

The VS Code migration guide was telling users the opposite of reality.
This PR fixes that and provides a central concept page that other docs
can link to.

## Changes

| File | Change |
|------|--------|
| `windows-and-projects.md` | New concept page |
| `SUMMARY.md` | Add to Working with Code section |
| `getting-started.md` | Note about sidebar default + link |
| `migrate/vs-code.md` | Fix "no multi-root" claim → explain sidebar
model |
| `reference/cli.md` | Link to concept page from flags section |
| `ai/parallel-agents.md` | Cross-reference in Multiple Projects section
|

## Test plan

- [ ] Verify page renders correctly on docs site
- [ ] Check all internal links resolve
- [ ] Confirm `{#kb projects::OpenRecent}` renders the correct
keybinding

Release Notes:

- N/A

docs/src/SUMMARY.md

@@ -27,6 +27,7 @@
 
 # Working with Code
 
+- [Windows & Projects](./windows-and-projects.md)
 - [Editing Code](./editing-code.md)
   - [Code Completions](./completions.md)
   - [Snippets](./snippets.md)

docs/src/ai/parallel-agents.md

@@ -49,7 +49,7 @@ Each thread can use a different agent, so you can run Zed's built-in agent in on
 
 ## Multiple Projects {#multiple-projects}
 
-The Threads Sidebar can hold multiple projects at once. Each project gets its own group with its own threads and conversation history.
+The Threads Sidebar can hold multiple projects at once. Each project gets its own group with its own threads and conversation history. This mirrors how Zed handles projects in general — see [Windows & Projects](../windows-and-projects.md) for more on how projects open and how to manage them.
 
 To add another project to the sidebar, click the **Add Project** button (open-folder icon) in the sidebar bottom bar. The popover that opens lists your recent projects and also provides **Add Local Folders** and **Add Remote Folder** buttons at the bottom.
 

docs/src/getting-started.md

@@ -27,6 +27,8 @@ zed ~/projects/my-app
 
 Or use `Cmd+O` (macOS) / `Ctrl+O` (Linux/Windows) to open a folder from within Zed.
 
+By default, new projects open in your current window's threads sidebar. To open in a new window instead, use `zed -n ~/projects/my-app` or press `Cmd+Enter` when selecting from Open Recent. See [Windows & Projects](./windows-and-projects.md) for more details.
+
 ### 2. Learn the Essential Commands
 
 | Action          | macOS         | Linux/Windows  |

docs/src/migrate/vs-code.md

@@ -186,7 +186,7 @@ Zed also supports per-project settings. You can find these in the Settings Edito
 
 ## Open or Create a Project
 
-After setup, press `Cmd+O` (`Ctrl+O` on Linux) to open a folder. This becomes your workspace in Zed. There's no support for multi-root workspaces or `.code-workspace` files like in VS Code. Zed keeps it simple: one folder, one workspace.
+After setup, press `Cmd+O` (`Ctrl+O` on Linux) to open a folder. By default, new folders open in the current window's threads sidebar, letting you work on multiple projects without juggling windows. See [Windows & Projects](../windows-and-projects.md) for details on managing multiple projects and opening in new windows.
 
 To start a new project, create a directory using your terminal or file manager, then open it in Zed. The editor will treat that folder as the root of your project.
 
@@ -252,25 +252,24 @@ Zed also supports chords (multi-key sequences) like `Cmd+K Cmd+C`, like VS Code
 
 ## Differences in User Interfaces
 
-### No Workspace
+### Projects and Windows
 
 VS Code uses a dedicated Workspace concept, with multi-root folders, `.code-workspace` files, and a clear distinction between “a window” and “a workspace.”
-Zed simplifies this model.
+Zed takes a different approach.
 
 In Zed:
 
-- There is no workspace file format. Opening a folder is your project context.
+- **Multiple projects in one window**: You can open multiple folders in the same window. Each appears in the threads sidebar on the left, and you can switch between them while preserving your layout and agent threads. See [Windows & Projects](../windows-and-projects.md).
 
-- Zed does not support multi-root workspaces. You can only open one folder at a time in a window.
+- **No workspace file format**: There’s no `.code-workspace` equivalent. Opening a folder is your project context.
 
-- Most project-level behavior is scoped to the folder you open. Search, Git integration, tasks, and environment detection all treat the opened directory as the project root.
+- **Add Folder to Project**: If you want multiple folders in the same project (like VS Code’s multi-root), use File > Add Folder to Project. This adds another root to your current project’s file tree.
 
-- Per-project settings are optional. You can add a `.zed/settings.json` file inside a project to override global settings, but Zed does not use `.code-workspace` files and won’t import them.
+- **Per-project settings are optional**: You can add a `.zed/settings.json` file inside a project to override global settings.
 
-- You can start from a single file or an empty window. Zed doesn’t require you to open a folder to begin editing.
+- **You can start from a single file or an empty window**: Zed doesn’t require you to open a folder to begin editing.
 
-The result is a simpler model:
-Open a folder → work inside that folder → no additional workspace layer.
+The result is flexibility without complexity: multiple projects per window via the sidebar, or multiple folders per project via Add Folder to Project.
 
 ### Navigating in a Project
 

docs/src/reference/cli.md

@@ -85,6 +85,8 @@ Reuse an existing window, replacing its current workspace with the new paths:
 zed -r ~/projects/different-project
 ```
 
+By default (without `-n`, `-a`, or `-r`), directories open in the current window's sidebar. You can change this default with the `cli_default_open_behavior` setting. See [Windows & Projects](../windows-and-projects.md) for more details.
+
 ### `--diff <OLD_PATH> <NEW_PATH>`
 
 Open a diff view comparing two files. Can be specified multiple times:

docs/src/windows-and-projects.md

@@ -0,0 +1,92 @@
+---
+title: Windows & Projects
+description: "How Zed handles multiple projects in windows, including the threads sidebar and options for opening in new windows."
+---
+
+# Windows & Projects
+
+Zed lets you work on multiple projects in a single window. Projects appear in the threads sidebar on the left, and you can switch between them while keeping your context intact.
+
+## How Projects Open
+
+By default, when you open a folder in Zed, it opens as a new project in your current window's threads sidebar rather than creating a new window. This keeps related work together and preserves your agent threads and layout.
+
+| Action             | Result                                    |
+| ------------------ | ----------------------------------------- |
+| File > Open        | Opens in current window (threads sidebar) |
+| File > Open Recent | Opens in current window (threads sidebar) |
+| Drag folder to Zed | Opens in current window (threads sidebar) |
+| `zed ~/project`    | Opens in current window (threads sidebar) |
+
+## Working with Multiple Projects
+
+When you have multiple projects open:
+
+- Click a project header to collapse or expand its threads; Cmd+click (macOS) or Ctrl+click (Linux/Windows) to switch to that project
+- Each project has its own file tree, git state, and search scope
+- Agent threads are tied to their project context
+- Your workspace layout (splits, tabs) is preserved per project
+
+Think of projects in the threads sidebar like browser tabs, but for repositories.
+
+## Opening in a New Window
+
+Sometimes you want a completely separate window. Here's how:
+
+### From Open Recent
+
+When using File > Open Recent ({#kb projects::OpenRecent}):
+
+- **Enter** or **click** opens in the current window (threads sidebar)
+- **Cmd+Enter** or **Cmd+click** (macOS) / **Ctrl+Enter** or **Ctrl+click** (Linux/Windows) opens in a new window
+
+### From the CLI
+
+Use the `-n` flag to force a new window:
+
+```sh
+zed -n ~/projects/other-project
+```
+
+Other CLI options for controlling window behavior:
+
+| Flag            | Behavior                                           |
+| --------------- | -------------------------------------------------- |
+| `-n`, `--new`   | Always open in a new window                        |
+| `-a`, `--add`   | Add to the current window's threads sidebar        |
+| `-r`, `--reuse` | Replace the current project in the existing window |
+
+See [CLI Reference](./reference/cli.md) for full details.
+
+### Via Settings
+
+You can change the default CLI behavior with the `cli_default_open_behavior` setting:
+
+```json [settings]
+{
+  "cli_default_open_behavior": "new_window"
+}
+```
+
+Options:
+
+- `existing_window` (default): Open folders in the current window's threads sidebar
+- `new_window`: Open folders in a new window
+
+This setting affects CLI and double-click behavior, not the File > Open menu.
+
+## Adding Folders to a Project
+
+If you want to add a folder to your current project (not as a separate project in the threads sidebar), you have several options:
+
+- **File menu**: File > Add Folder to Project
+- **Project panel**: Right-click in the project panel and choose "Add Folders to Project"
+- **Open Recent**: Select a recent project and click the "Add Folder to this Project" button
+
+This adds the folder as an additional root in your current project's file tree, similar to VS Code's multi-root workspaces.
+
+## See Also
+
+- [Threads Sidebar](./ai/parallel-agents.md#threads-sidebar): Managing threads across projects
+- [Getting Started](./getting-started.md): Essential commands and setup
+- [VS Code Migration](./migrate/vs-code.md): How Zed's project model differs from VS Code