Audited the AI documentation against the implementation
## Changes
- **tool-permissions**: `skill` tool patterns match the absolute
`SKILL.md` path, not the skill name (fixed the table, example pattern,
and added a clarifying note).
- **external-agents**: Gemini CLI receives Zed's Google AI key when no
env key is set; extension-provided agents are deprecated in favor of the
ACP registry.
- **inline-assistant**: alternatives run alongside the inline assistant
model (not just the default model); fixed a broken anchor and
`gpt-4-mini` → `gpt-5-mini` model id typos.
- **mcp**: corrected the extensions menu item name ("Install New
Servers…"), the remote server `url` example, and removed the nonexistent
`thinking` tool from the profile example.
- **agent-panel**: "New From Summary" lives in the New Thread menu;
corrected the `@`-mention type list (no "instruction files"; added Fetch
and Branch Diff).
- **use-api-access**: DeepSeek default `api_url` includes `/v1`.
- **skills**: folder name is a convention not a requirement; long
descriptions warn rather than fail (measured in bytes); hidden skills
are also `@`-mentionable; dropped the unenforced consecutive-hyphen
rule; reconciled the no-remote-registry note with GitHub import.
- **edit-prediction**: `alt-tab` and `alt-l` are bound across platforms;
predictions are throttled rather than fired on every keystroke.
- **getting-started, windows-and-projects, parallel-agents**: Panel
Layout lives in the title-bar user menu, with
`workspace::UseAgenticLayout`/`UseClassicLayout` action references.
Release Notes:
- N/A
---------
Co-authored-by: zed-zippy[bot] <234243425+zed-zippy[bot]@users.noreply.github.com>
## Summary
- Restructures the AI docs around quick routing, agent paths, provider
access, and company-specific entry points.
- Moves account-owned AI billing/model pages into Account & Billing
while preserving legacy AI redirects.
- Adds focused pages for Zed Agent, external agents, terminal threads,
agent profiles, skills, instructions, API access, subscriptions,
gateways, and local models.
- Updates related links across Git, authentication, business, migration,
and settings reference docs.
## Validation
- `pnpm dlx prettier@3.5.0 . --write`
- `pnpm dlx prettier@3.5.0 . --check`
- `git diff --check -- docs/src`
- Changed-doc local markdown link sanity check
- `mdbook build docs` was attempted; it is currently blocked by an
unrelated existing `docs/src/vim.md:542` action schema error for
`vim::HelixJumpToWord`.
## Follow-up
- Create a ticket to align Zed's in-app AI configuration surfaces with
this documentation model, including Agent Settings, Configure buttons,
Tools, Profiles, MCP, Skills/Instructions, and plain settings.
## Suggested .rules additions
N/A
Release Notes:
- N/A
## 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
