## Summary
- Adds 63 internal links across 41 documentation pages.
- Connects existing terms such as Agent Panel, semantic tokens, edit
predictions, and language-specific debugging to their detailed reference
pages.
- Uses existing wording for 60 links and makes three small wording
changes where a natural anchor did not already exist.
## Why this matters
Readers can now move from overview and configuration pages to the
relevant detailed guidance without searching the documentation manually.
The changes add navigation only. They do not change product behavior or
documented requirements.
## Jev experiment
This PR came from a local experiment using Jev to audit internal links
across the published documentation. The audit scripts are not included
in this PR.
- Code shortlisted 2,715 possible source and destination page pairs.
- Jev made two separate decisions for each pair: whether the link would
help the reader, and which exact existing phrase should become the
anchor.
- Five strong links without existing anchor text went to GPT-5.6 Luna
for minimal rewrite options. Jev then selected among those fixed
options.
- A local review interface surfaced the results for Pass or Fail
decisions before any files changed.
Human review approved 66 changes. Two no longer matched the current
`main` branch, and review removed one circular link, leaving the 63
links in this PR.
## Validation
- `pnpm dlx prettier@3.5.0 <changed docs> --check`
- `lychee --exclude '^http' './docs/src/**/*'` — 0 errors
- `mdbook build docs`
- Verified that the diff adds exactly 63 Markdown links
Release Notes:
- Improved links between related documentation pages.
Fixes https://github.com/zed-industries/zed/issues/63672
OpenCode Go now requires the `x-opencode-session` header on every model
request. Zed previously sent the header only when a request already had
a thread ID, so inline assistance, terminal assistance, and other
standalone requests could omit it and risk rejection.
This change makes the OpenCode provider add the header to every request.
Existing thread and assist session IDs are reused when available.
Standalone requests receive a generated non-empty ID. Thread title and
summary requests now carry the thread ID so related requests keep the
same session scope.
The change also adds tests for missing, empty, and invalid IDs, plus a
wire-level test that verifies the header reaches the HTTP client. The
provider test file stays separate so the implementation remains under
1,000 lines.
Testing:
- `cargo fmt --all -- --check`
- Focused OpenCode, thread summary, and thread title tests
- `cargo check -p agent_ui -p sidebar`
- `GITHUB_ACTIONS=1 ./script/clippy -p language_models`
- `git diff --check`
Release Notes:
- Fixed OpenCode Go requests that could fail when Zed omitted the
session header.
---------
Co-authored-by: Kirill Bulatov <kirill@zed.dev>
Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com>
The hosted-model reference now includes Claude Opus 5. This closes the
gap between the public documentation and the models that `cloud`
currently offers to Zed Pro and Zed Business customers.
The pricing table lists the provider price and Zed price for input,
output, cache-write, and cache-read tokens. The context-window table
lists the current 1M-token hosted limit. This change does not alter
model access or billing behavior.
Testing performed:
- `cd docs && npx prettier --check src/account/zed-hosted-models.md`
- `cd docs && mdbook build`
Release Notes:
- N/A
## Summary
- Document pricing and Zed-hosted context limits for Claude Fable 5,
Claude Sonnet 5, and GPT-5.6 Sol, Terra, and Luna.
- Record recent Gemini and xAI model retirements and replacement
guidance.
- Put the Fable safety-retention warning on the hosted-model reference
and align the privacy docs with the current Anthropic Covered Models
terminology and retention period.
## Sources
- zed-industries/cloud origin/main at
f5d109a868a303241e89ea30d6da8da19699ead4
- OpenAI GPT-5.6 model documentation
- Anthropic Covered Models retention policy
- xAI May 15, 2026 model retirement guide
## Testing
- pnpm dlx prettier@3.5.0 . --check
- mdbook build docs
Release Notes:
- N/A
Context
This PR makes the Zed docs easier for AI tools, search crawlers, and
users to consume without changing the visible docs content. The current
production docs are primarily optimized for browser navigation. They do
not expose first-class Markdown URLs, an `llms.txt` index, page-level
copy affordances, or machine-readable freshness metadata that let users
and agents grab clean, current page content.
Changes
- Generate Markdown copies for docs pages during the mdBook postprocess
step, including `/docs/index.md` as an alias for Getting Started.
- Generate `/docs/llms.txt` from the mdBook chapter list, grouped by
`SUMMARY.md` sections and annotated with page frontmatter descriptions.
- Generate `/docs/sitemap.xml` with `<lastmod>` values for every docs
page.
- Emit machine-readable freshness metadata in HTML via `last-modified`
and `article:modified_time` meta tags.
- Generate Cloudflare Pages `_redirects` for `.html`, extensionless, and
`.md` redirect variants, with channel-aware docs destinations.
- Add discovery hints for agents and crawlers: `rel="llms.txt"`,
`rel="alternate" type="text/markdown"`, and a short generated `llms.txt`
directive in copied Markdown pages.
- Update the docs proxy so `Accept: text/markdown`, `/docs.md`, and
direct `.md` requests can resolve to the generated Markdown artifacts.
- Move primary docs content earlier in the HTML source while preserving
the visible layout, so crawlers and agent scorers encounter the article
before sidebar chrome.
- Move the existing copy-as-Markdown control from the top navigation
into the page-title row, using the generated Markdown alternate link as
the source of truth.
- Split AI-discovery artifact generation out of
`docs_preprocessor/src/main.rs` into a focused module.
Best Practices Adopted
- Use `llms.txt` as a concise navigation index, not a dump of full page
content.
- Link to absolute, canonical Markdown URLs from `llms.txt`.
- Preserve the docs hierarchy in `llms.txt` instead of emitting a flat
sitemap-like list.
- Include short per-link descriptions from existing metadata rather than
inventing summaries.
- Keep `llms.txt`, Markdown copies, sitemap data, redirects, and
freshness metadata generated from the same mdBook source to avoid drift.
- Advertise Markdown alternates with standard HTML metadata and
same-origin URLs.
- Support both explicit Markdown URLs and content negotiation for
clients that prefer Markdown.
- Keep browser copy behavior pointed at generated Markdown alternate
links instead of duplicating route inference in JavaScript.
- Keep the copy-as-Markdown affordance in the page title row without
duplicating header chrome controls.
Validation
- `cargo check -p docs_preprocessor`
- `cargo test -p docs_preprocessor`
- `./script/clippy -p docs_preprocessor`
- `mdbook build ./docs --dest-dir=../target/deploy/docs/`
- `node --check docs/theme/plugins.js`
- `pnpm dlx prettier@3.5.0 docs/theme/plugins.js --check`
- `git diff --check`
- Local artifact checks confirmed generated Markdown pages, `llms.txt`,
`sitemap.xml` lastmod values, HTML freshness metadata, Markdown
alternate links, redirect targets, and preprocessed action/keybinding
tags resolve as expected.
- Worker URL rewrite mock covered `/docs/`, `/docs.md`,
`/docs/index.md`, extensionless docs routes, `.html` routes,
`/docs/llms.txt`, and `/docs/sitemap.xml`.
- High-effort adversarial subagent review found blockers around
channel-aware redirects, shallow-checkout date fallback, file size,
duplicated Markdown path inference, and process spawning. Those were
addressed.
Remaining Notes
- Local `python -m http.server` does not emulate Cloudflare Pages pretty
URLs, `_redirects`, or the docs-proxy Worker, so full local `afdocs`
still cannot prove content negotiation end to end.
- Existing production remains unchanged until this PR is deployed
through the docs workflow.
- Production baseline `npx afdocs check https://zed.dev/docs/ --fixes
--verbose` still reports the original failures before this PR is
deployed: 12 passed, 8 failed, 3 skipped.
Release Notes:
- Improved docs AI-readiness by adding machine-readable discovery,
Markdown access, and freshness metadata.
---------
Co-authored-by: Katie Geer <katie@zed.dev>
Co-authored-by: Ben Kunkle <ben@zed.dev>
Anthropic now requires limited data retention for models it designates
as covered models (Mythos-class models, such as Claude Fable 5): prompts
and outputs are retained for 30 days for trust and safety purposes, on
every platform where these models are offered, including platforms with
zero-data-retention agreements. See [Anthropic's public
policy](https://support.claude.com/en/articles/15425996-data-retention-practices-for-mythos-class-models).
Our AI privacy docs previously described zero data retention as applying
to all Zed-hosted models unconditionally. This PR updates them to
document the exception:
- `docs/src/ai/privacy-and-security.md`: Adds a "Provider Safety
Retention for Designated Models" section covering what is retained, by
whom, for how long, that no-training commitments still apply, and that
bringing your own key does not avoid retention for covered models.
Qualifies the intro, request-path table, and provider commitments table
accordingly.
- `docs/src/ai/ai-improvement.md`: Qualifies the zero-data-retention
statements and links to the new section.
- `docs/src/business/privacy.md`: Qualifies the zero-data-retention
statement and links to the new section.
Release Notes:
- N/A
## 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
- add Billing Manager to the organization roles docs with a capability
matrix
- update Business and billing docs to explain non-paid-seat billing
access
- update billing docs for self-serve tax ID updates
Release Notes:
- N/A
This updates docs to reflect changes threshold billing behavior for
individual Zed Pro subscriptions.
- Scope threshold billing language explicitly to individual Zed Pro
subscriptions.
- Remove stale language saying each $10 threshold crossing resets the
threshold to $0.
- Document that threshold invoices start at $10, may rise in $10
increments up to $100, and are not automatically lowered during the same
subscription.
- Split spend-limit docs between Zed Pro and Zed Business, with Business
readers linked to organization billing.
Release Notes:
- N/A
## Summary
This moves the remaining first-party AGPL surface to GPL, a less
restrictive license for these components. Apache-2.0 components are
unchanged.
Changes:
- Updates the `collab` crate from `AGPL-3.0-or-later` to
`GPL-3.0-or-later`
- Removes the root AGPL license file and first-party crate AGPL symlinks
- Updates web, documentation, Flatpak, README, and terms references to
reflect the GPL/Apache licensing split
- Updates the open-source component example list in the terms and
regenerates the RTF copy; no other terms changes are intended
- Adds guardrails so first-party crates cannot declare AGPL licensing or
carry `LICENSE-AGPL` files
Release timing: preview during the week of June 1, 2026; stable during
the week of June 8, 2026.
## Residual AGPL/Affero references
- `LICENSE-GPL`: GPLv3's own compatibility clause; unchanged official
license text.
- `crates/json_schema_store/src/schemas/package.json`: generic npm
package-license schema value, not Zed licensing.
- `script/check-licenses`, `script/new-crate`,
`script/licenses/zed-licenses.toml`: guardrails that reject or warn
against reintroducing AGPL.
## Verification
- `script/check-licenses`
- `script/generate-licenses`
- `script/generate-terms-rtf`
- `script/new-crate license_probe_for_gpl`, then discarded generated
crate
- `script/new-crate license_probe_for_agpl agpl` fails as expected
- `mdbook build docs`
- `./script/clippy`
- `git grep -n -I -E "AGPL|Affero"`
- `git diff --check`
Release Notes:
- The `collab` crate, used to implement Zed's collaboration backend, is
now licensed under the GPL instead of the AGPL. The AGPL license is no
longer used in the zed repository.
## Summary
This started from #57636, after we saw ChatGPT subscription/Codex
requests stall over the past week. OpenCode v1.15.11 shipped related
resilience fixes for the same class of Codex subscription endpoint
issues, so this ports the relevant pieces into Zed's native ChatGPT
subscription provider.
When Zed asks ChatGPT/Codex for a response, sometimes the server
connection can get stuck before it even sends the first response
headers. Before this PR, Zed could wait indefinitely, which looks like
OpenCode/Zed “stalling.”
This PR makes Zed:
- Wait up to 10 seconds for the server to start responding.
- If nothing comes back in that window, treat it as a temporary
network/API failure.
- Let the existing retry logic try again instead of leaving the user
stuck.
- Send a stable session-id header so OpenAI’s Codex backend can
associate requests with the same Zed agent thread.
- Add tests to make sure:
- stuck-before-response requests time out,
- normal slow streaming responses are not cut off,
- ChatGPT subscription requests send the right session header,
- the agent retries this kind of failure.
intended user-facing result is: fewer “the assistant is just sitting
there forever” failures when using ChatGPT subscription models.
## Verification
- cargo test -p open_ai responses
- cargo test -p language_models openai_subscribed
- cargo test -p agent test_send_retry_on_http_send_error
- cargo check -p open_ai
- cargo check -p language_models
- cargo check -p agent
Release Notes:
- Fixed ChatGPT subscription requests stalling indefinitely before
response headers arrive.
## Summary
- Document that Zed-hosted Gemini models do not use Google context
caching
- Clarify that Gemini usage is billed only as input and output tokens,
with no cached-input price
- Link to Google's Vertex AI context caching and zero-data-retention
documentation for background
## Validation
- `script/generate-action-metadata`
- `mdbook build docs`
Release Notes:
- N/A
## Summary
- Document the new ChatGPT Subscription provider from #53166
- Add to the LLM Providers page alphabetically between Anthropic and
DeepSeek
- Cover sign-in flow, available models (GPT-5.5, GPT-5.3 Codex), and
sign-out
## Test plan
- [ ] Verify section renders correctly in docs preview
- [ ] Confirm links and anchors work
Release Notes:
- N/A
Adds a new language model provider that lets users authenticate with
their ChatGPT Plus/Pro subscription and use OpenAI models
(codex-mini-latest, o4-mini, o3) directly in the Zed agent — without
needing a separate API key.
## How it works
1. **OAuth 2.0 + PKCE sign-in**: Uses OpenAI's official Codex CLI client
ID to run an authorization code flow. A local HTTP server on
`127.0.0.1:1455` captures the callback, exchanges the code for tokens,
and stores them in the system keychain.
2. **Token refresh**: Access tokens are automatically refreshed when
they're within 5 minutes of expiry, using the stored refresh token.
3. **Responses API**: Requests go to
`https://chatgpt.com/backend-api/codex/responses` using the existing
`open_ai::responses` client (Responses API format, not Chat Completions
which was deprecated for this endpoint in Feb 2026).
4. **Required headers**: `originator: zed`, `OpenAI-Beta:
responses=experimental`, `ChatGPT-Account-Id` (extracted from JWT),
`store: false` in the body.
## Files changed
- `crates/open_ai/src/responses.rs`: Add `store: Option<bool>` field to
`Request`; add `extra_headers` param to `stream_response` for
per-provider header injection
- `crates/language_models/src/provider/openai_subscribed.rs`: New
provider (sign-in UI, OAuth flow, token storage/refresh, model list)
- `crates/language_models/src/provider/open_ai.rs`,
`open_ai_compatible.rs`, `opencode.rs`: Pass `vec![]` for new
`extra_headers` param
- `crates/language_models/src/language_models.rs`: Register the new
provider
- `crates/language_models/Cargo.toml`: Add `rand` and `sha2` deps for
PKCE
## Open questions / known gaps
- [ ] **Terms of service**: Usage appears to be within OpenAI's ToS
(interactive use via their official CLI client ID), but needs legal
sign-off before shipping
- [ ] **Redirect URI**: Currently `http://localhost:1455/auth/callback`
— may need to match exactly what OpenAI's Codex CLI uses
- [ ] **UI polish**: The sign-in card is functional but minimal; needs
design review
- [ ] **Error messages**: OAuth error responses from the callback URL
aren't surfaced to the user yet
- [ ] **`o3` availability**: o3 may require a higher subscription tier;
consider gating it
## Testing
Sign-in flow was designed to match the Copilot Chat provider pattern.
Manual testing against the live OAuth endpoint is needed.
Release Notes:
- Added ChatGPT subscription provider, allowing users to use their
ChatGPT Plus/Pro subscription with the Zed agent
---------
Co-authored-by: Zed Zippy <234243425+zed-zippy[bot]@users.noreply.github.com>
Co-authored-by: Richard Feldman <richard@zed.dev>
Co-authored-by: Richard Feldman <oss@rtfeldman.com>
Co-authored-by: Agus Zubiaga <agus@zed.dev>
## 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
## Summary
- Restructures docs nav: new **Account & Billing**, **Zed Business**,
and **Privacy & Security** sections, positioned above Platform Support
- Moves Plans & Pricing and Billing out of AI > Subscription into
Account & Billing
- Moves Models and Providers to direct children of AI (removes
Subscription wrapper)
- Adds 4 new Zed Business pages: Overview, Organizations, Admin
Controls, Business Support
- Existing `roles.md` wired in as Roles & Permissions
- Privacy & Security, Privacy for Business, and SOC2 remain as draft
entries pending BIZOPS-983
- Adds redirect: `/ai/subscription.html` →
`/docs/ai/plans-and-usage.html`
## Status
Draft — active work in progress. Remaining issues on this branch:
- BIZOPS-982 (due 3/21): Account & Billing content updates
- BIZOPS-983 (due 3/23): Privacy & Security content
- BIZOPS-984 (due 3/25): Final review and QA
## Notes for reviewers
- Implementation-specific UI flows in the Business pages are stubbed
with `<!-- TODO -->` comments — these need to be filled in closer to
launch once the dashboard is finalized
Release Notes:
- N/A
---------
Co-authored-by: Zed Zippy <234243425+zed-zippy[bot]@users.noreply.github.com>
Co-authored-by: Katie Geer <katie@zed.dev>
Co-authored-by: Marshall Bowers <git@maxdeviant.com>
## Summary
- Add pricing table entries for GPT-5.5 and GPT-5.5 pro
- Add context window entries for GPT-5.5/5.5 pro (272k)
- Fix context window values for all OpenAI models from 400k to 272k to
match actual cloud-enforced limit
- Update student plan note to exclude GPT-5.5 pro
- Update page description
Follows up on #54820 which added code support for GPT-5.5 models.
The 272k limit is enforced in the cloud due to context-tiered pricing
not yet being implemented.
## Test plan
- [ ] Verify pricing matches cloud repo configuration
- [ ] Check docs render correctly
Release Notes:
- N/A
## Summary
- Add a new "Configuration Boundaries" section to the external agents
documentation explaining what settings are shared between Zed and ACP
agents
- Clarify bidirectional configuration story: what Zed forwards to agents
AND what agents inherit from native installations
- Add troubleshooting section for common user confusion points
- Update MCP docs with clearer cross-links
## Context
Users are confused about which Zed settings apply to external ACP agents
like Claude and Codex. Common questions:
- "I configured MCP in Zed but Claude can't see it"
- "My Codex config.toml isn't being used"
- "Do profiles apply to external agents?"
## Key Points
**What Zed forwards to ACP agents:**
- Model/mode selection, env vars, MCP servers (with limitations),
CLAUDE.md
**What's NOT forwarded:**
- Profiles, tool permissions settings, `.rules` files
**What agents DON'T inherit from native installations:**
- `~/.claude/` config, `~/.codex/config.toml`, native MCP servers,
authentication state
## Test plan
- [x] Review for technical accuracy against codebase
- [x] Check brand voice compliance
Release Notes:
- N/A
## Summary
- Add Claude Opus 4.7 to the pricing table with same rates as Opus 4.6
- Add Claude Opus 4.7 to context windows table (1M context)
- Update model retirements to include Opus 4.7 as upgrade path from Opus
4.1
- Add Opus 4.7 to Bedrock extended context section
Release Notes:
- N/A
## Summary
The docs preprocessor was configured with `renderer = ["html"]`, but the
actual output renderer is `zed-html`. This mismatch caused mdbook to
skip the preprocessing step, leaving YAML frontmatter unprocessed in the
rendered HTML.
**Symptoms:**
- YAML frontmatter (`---\ntitle: ...\n---`) leaked into rendered HTML
- `---` rendered as `<hr />`
- Frontmatter fields appeared as `<h2>` headings (setext heading
interpretation)
- Meta description tags showed default values instead of page-specific
descriptions
## Root Cause
The `renderer = ["html"]` config was introduced in August 2024 (#16883)
when the preprocessor was first added. At that time, the output was the
standard `html` renderer.
In July 2025 (#35112), the `[output.zed-html]` custom renderer was added
for frontmatter/postprocessing support, but the preprocessor's
`renderer` filter wasn't updated to match.
**Why it broke now (April 12, 2026):**
The mismatch was latent - it worked inconsistently depending on CI
environment conditions. Comparing two deploys from the same day:
| Deploy | Network Errors | Preprocessing |
|--------|---------------|---------------|
| 19:00 UTC | 0 | ✓ Runs correctly |
| 21:54 UTC | Many (`static.crates.io` connection failures) | ✗ Skipped
|
The 21:54 deploy had network errors during `cargo run -p
docs_preprocessor`. mdbook appears to have silently skipped the
preprocessor and proceeded directly to the renderer. The postprocessor
still ran (via the renderer's separate cargo command), but without
preprocessing, frontmatter wasn't converted to metadata.
**The fix:** Change `renderer = ["html"]` to `renderer = ["html",
"zed-html"]` to support both the custom renderer and any fallback to the
standard html renderer (e.g., during local development or if mdbook
commands internally use html).
## Test plan
- [x] Local build produces correct HTML without frontmatter leaking
- [x] Meta descriptions correctly populated from frontmatter
- [x] CI `check_docs` shows all 3 preprocessor steps running:
- `docs_preprocessor supports zed-html`
- `docs_preprocessor` (preprocessing)
- `docs_preprocessor postprocess`
Release Notes:
- N/A
## Summary
- Update the context window table in `models.md` to reflect that Claude
Sonnet 4.6 and Opus 4.6 now support 1M token context windows (previously
listed as 200k)
- Remove Sonnet 4.5/4.6 from the "may increase in future releases"
callout since the 4.6 models are now at 1M
Release Notes:
- N/A
## Summary
Fixes issues discovered while running the docs automation workflow for
the first time, plus improvements based on the v0.225 run where 44
suggestions overwhelmed a single Droid invocation.
### docs-suggest-publish
- Ignore untracked files when checking for clean working directory
- Add `--auto high` flag to droid exec for non-interactive use
- Add error handling to show droid output on failure
- Remove non-existent `documentation` label from PR creation
- Use `--write` flag for prettier to fix formatting
- **Batch suggestions** into groups of 10 (configurable with
`--batch-size`) to prevent Droid from dropping suggestions when context
is too large
- **Pre-PR docs build validation** — runs `generate-action-metadata` +
`mdbook build` before creating the PR to catch invalid `{#action}` and
`{#kb}` references locally instead of waiting for CI (skippable with
`--skip-validation`)
- **Prompt guardrail** — instructs Droid not to invent `{#kb}` or
`{#action}` references, only reusing action names already present in
docs files
- **Stable release detection** — at publish time, checks each queued
PR's merge commit against the latest stable release tag. PRs already in
stable get annotated "ALREADY IN STABLE" so Droid applies content
changes without adding incorrect Preview callouts
- **Feature flag detection** — parses
`crates/feature_flags/src/flags.rs` for all feature flag struct names,
then checks each PR's diff for references. PRs behind feature flags are
skipped entirely since those features aren't generally available yet
### docs-strip-preview-callouts
- Remove non-existent `documentation` label from PR creation
- Add `Release Notes: - N/A` to generated PR body (fixes Danger bot
check)
## Context
These scripts were run for the first time as part of the v0.225 release.
Issues found:
1. The `documentation` label doesn't exist in this repo
2. Droid exec needs `--auto high` for non-interactive execution
3. Prettier needs `--write` to actually fix files (was running in check
mode)
4. Untracked files should not block the workflow
5. Sending all 44 suggestions in one Droid invocation only applied 2 —
batching in groups of 10 fixed this
6. Droid hallucinated action names (`settings::OpenSettings`,
`gpui::Modifiers::secondary_key`) that broke the docs preprocessor build
7. PRs that shipped in stable v0.225 incorrectly got Preview callouts
because the queue doesn't distinguish preview-only from
already-in-stable
8. PRs behind feature flags (subagents, git graph) got documented
despite not being generally available
Release Notes:
- N/A
This PR removes Preview callouts from documentation for features that
are now in Stable.
Features documented with Preview callouts are now included in the stable
release.
Generated by script/docs-strip-preview-callouts
Release Notes:
- N/A
## Summary
Add a standalone **humanizer** skill based on Wikipedia's "Signs of AI
writing" guide that detects and fixes 24 common AI-writing patterns.
Also update brand-writer to recommend running humanizer as a
pre-validation step for high-stakes content.
## Details
**New skill: `/humanizer`**
- Detects 24 AI-writing anti-patterns from Wikipedia's guide (maintained
by WikiProject AI Cleanup)
- Covers content patterns (significance inflation, vague attributions),
language patterns (copula avoidance, synonym cycling), style patterns
(em dash overuse, boldface), and communication patterns (chatbot
artifacts, sycophantic tone)
- Includes a two-pass audit workflow: draft rewrite → "What makes this
obviously AI generated?" → final revision
- Adds guidance on injecting "soul" and personality, not just removing
bad patterns
**Updated: brand-writer**
- Added Phase 4 "Humanizer Pass" recommending `/humanizer` for
high-stakes content (homepage, announcements, product pages)
- Phases renumbered (Validation is now Phase 5)
## Attribution
Based on [blader/humanizer](https://github.com/blader/humanizer) and
[Wikipedia:Signs of AI
writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing).
Release Notes:
- N/A
## Summary
Fixes **ZED-2XA** — "Unexpected duplicated status entries: Untracked and
Untracked" crash.
**Impact:** 22 occurrences, 3 users affected (Sentry). The panic was
introduced in #23483 (2025-01-22) which added the `dedup_by` logic for
handling deleted-in-index + untracked file combinations.
No related GitHub issues were found filed against this crash.
## Root Cause
`GitStatus::from_str` sorts entries by path and then calls `dedup_by` to
merge duplicate entries. The only handled case was `(INDEX_DELETED,
Untracked)` — all other duplicates hit a catch-all `panic!`. In
practice, git can produce duplicate `??` (untracked) entries for the
same path, which triggered this crash.
## Fix
- Identical duplicate statuses (e.g., `Untracked, Untracked`) are now
silently deduplicated (keep one)
- Other unexpected duplicate combinations log a warning instead of
crashing
- Added a regression test that parses `"?? file.txt\0?? file.txt"` and
verifies it produces a single entry
## Verification
- Reproduction test passes: `cargo test -p git --
test_duplicate_untracked_entries`
- Full crate tests pass: `cargo test -p git` (20/20)
- Clippy clean: `./script/clippy`
Release Notes:
- Fixed a crash when git produces duplicate status entries for the same
file path
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Disable the cron schedule for the background agent MVP workflow. Manual
runs via workflow_dispatch are still available.
The workflow was running daily on weekdays but the project is being
paused. This change:
- Comments out the schedule trigger
- Adds a note pointing to the Notion doc for context
- Preserves the ability to run manually
See [Background Agent for
Zed](https://www.notion.so/Background-Agent-for-Zed-3038aa087eb980449b9ee02f70ae8413)
Notion doc for current status and contacts to resume this work.
Release Notes:
- N/A
## Summary
Fork PRs don't have access to repository secrets (`FACTORY_API_KEY`),
causing the docs suggestions workflow to fail when triggered by external
contributor PRs.
This adds a condition to skip the `batch-suggestions` job when the PR
originates from a fork (`github.event.pull_request.head.repo.full_name
!= github.repository`).
## Context
See failing job:
https://github.com/zed-industries/zed/actions/runs/22323201362/job/64586740764
The `pull_request` trigger doesn't pass secrets to workflows running on
fork PRs for security reasons. This is expected GitHub behavior.
Release Notes:
- N/A
This draft PR auto-applies queued documentation suggestions collected
from recently merged PRs.
34 documentation suggestions from merged PRs were processed. See the
commit message for the full list.
Release Notes:
- N/A
---------
Co-authored-by: Katie Geer <katie@zed.dev>
## Summary
Fixes the `SyntaxError: Unexpected identifier 'gemini'` error in the
cherry-pick documentation suggestions workflow.
## Problem
The 'Post suggestions as PR comment' step was directly interpolating
markdown content into a JavaScript template literal:
```javascript
const suggestions = `${{ steps.analyze.outputs.suggestions }}`;
```
When the suggestions contained backticks, `${}` sequences, or other
special characters (like the `gemini-3.1-pro-preview` model name in
markdown code blocks), it broke the JavaScript syntax.
## Solution
Write suggestions to a file in `$RUNNER_TEMP` and read it using
`fs.readFileSync()` in the script step. This avoids all GitHub Actions
template interpolation and JavaScript string parsing issues.
## Testing
This should fix the failed run:
https://github.com/zed-industries/zed/actions/runs/22194396124/job/64190762087
Release Notes:
- N/A
## Summary
- Added Gemini 3.1 Pro to the pricing table, context windows table, and
page metadata in `docs/src/ai/models.md`
- Listed alongside existing Gemini 3 Pro (both remain available)
Release Notes:
- N/A
Add exponential backoff retry logic (3 attempts with 5s/10s/15s delays)
to the Droid CLI installation and
docs-suggest script execution steps in both the batch-suggestions and
cherry-pick-suggestions jobs.
This handles intermittent Factory API authentication issues that can
cause workflow failures when the API is temporarily unavailable or
rate-limited.
Release Notes:
- N/A
Fixes the workflow failure where `gh auth login --with-token` fails
because `GH_TOKEN` is already set in the environment.
The error was:
```
The value of the GH_TOKEN environment variable is being used for authentication.
To have GitHub CLI store credentials instead, first clear the value from the environment.
```
The fix uses a subshell to unset `GH_TOKEN` before calling `gh auth
login`:
```bash
echo "$GH_TOKEN" | (unset GH_TOKEN && gh auth login --with-token)
```
Release Notes:
- N/A
Fix git auth conflict in background_agent_mvp workflow
The workflow was manually configuring git authentication with:
```bash
git config --local http.https://github.com/.extraheader "AUTHORIZATION: bearer ..."
```
This conflicted with the authentication already set up by
`actions/checkout@v4`, which uses `AUTHORIZATION: basic ...`.
The conflict caused all crash pipeline runs to fail with:
```
fatal: could not read Username for 'https://github.com'
```
This morning's run (22147984206) failed for all 15 crash candidates
(ZED-4VS, ZED-202, etc.) with this error.
Remove the redundant git config since actions/checkout already handles
authentication properly.
Release Notes:
- N/A
Fixes two issues in the documentation suggestions workflow:
1. **Shell quoting bug**: PR titles containing quotes (e.g., `agent_ui:
Add the ability to undo "reject all"`) were breaking the shell script
because the title was substituted directly into the script. Moved
`PR_TITLE`, `PR_NUM`, and `OUTPUT_FILE` to environment variables where
special characters are handled safely.
2. **GH CLI auth issue**: The `gh` CLI sometimes fails to auto-detect
`GH_TOKEN` in the environment, causing `gh pr view` and `gh pr diff` to
fail with "Bad credentials". Added explicit `gh auth login --with-token`
in both the batch-suggestions and cherry-pick-suggestions jobs.
Release Notes:
- N/A
## Summary
- Update hosted model and context-window tables in docs/src/ai/models.md
to remove retired models and list current replacements.
- Add a dated Recent Model Retirements section mapping each retired
model to its replacement.
- Update AI docs examples and references in agent-settings.md,
inline-assistant.md, agent-panel.md, and llm-providers.md to use current
model names.
- Remove stale OpenAI model references in llm-providers.md that no
longer align with currently offered hosted models.
## Validation
- ./script/prettier
- ./script/check-todos
## Suggested .rules additions
- N/A
Release Notes:
- N/A
Adds scripts and a GitHub Action workflow for automatically suggesting
documentation updates when PRs modify user-facing code.
## Scripts
- **`script/docs-suggest`**: Analyze PRs/commits for documentation needs
using AI
- **`script/docs-suggest-publish`**: Create a PR from batched
suggestions
- **`script/docs-strip-preview-callouts`**: Remove Preview callouts when
shipping to stable
- **`script/test-docs-suggest-batch`**: Testing utility for batch
analysis
## Workflow
The GitHub Action (`.github/workflows/docs_suggestions.yml`) handles two
scenarios:
1. **PRs merged to main**: Suggestions are batched to
`docs/suggestions-pending` branch for the next Preview release
2. **Cherry-picks to release branches**: Suggestions are posted as PR
comments for immediate review
## Callout Types
The system distinguishes between:
- **Additive features** (new commands, settings, UI):
```markdown
> **Preview:** This feature is available in Zed Preview. It will be
included in the next Stable release.
```
- **Behavior modifications** (changed defaults, altered existing
behavior):
```markdown
> **Changed in Preview (v0.XXX).** See [release notes](/releases#0.XXX).
```
Both callout types are stripped by `docs-strip-preview-callouts` when
features ship to stable.
## Example Output
See PR #49190 for example documentation suggestions generated by running
this on PRs from the v0.224 preview window.
## Usage
```bash
# Analyze a PR (auto-detects batch vs immediate mode)
script/docs-suggest --pr 49100
# Dry run to see assembled context
script/docs-suggest --pr 49100 --dry-run
# Create PR from batched suggestions
script/docs-suggest-publish
# Strip callouts for stable release
script/docs-strip-preview-callouts
```
Release Notes:
- N/A
## Summary
- refresh git auth headers before each per-crash iteration in
`background_agent_mvp`
- add guarded `git fetch`/`git checkout` handling so one candidate auth
failure doesn’t fail the entire run
## Context
- fixes the auth failure seen in workflow run 22106378719 (`fatal: could
not read Username for 'https://github.com'`)
- related Linear issue: BIZOPS-853
## Testing
- ruby -e "require 'yaml';
YAML.load_file('.github/workflows/background_agent_mvp.yml')"
Release Notes:
- N/A
## Summary
- add a new crash issue-linking subagent prompt
(`.factory/prompts/crash/link-issues.md`)
- add a scheduled/manual GitHub workflow for week-one background-agent
runs (`.github/workflows/background_agent_mvp.yml`)
- add Sentry candidate selection script to rank top crashes by
solvability × population (`script/select-sentry-crash-candidates`)
- add a local dry-run runner for end-to-end MVP execution without
push/PR actions (`script/run-background-agent-mvp-local`)
## Guardrails in this MVP
- draft PRs only (no auto-merge)
- reviewer routing defaults to: `eholk,morgankrey,osiewicz,bennetbo`
- pipeline order is: investigate -> link-issues -> fix
## Validation
- `python3 -m py_compile script/select-sentry-crash-candidates
script/run-background-agent-mvp-local`
- `python3 script/select-sentry-crash-candidates --help`
- `python3 script/run-background-agent-mvp-local --help`
---------
Co-authored-by: John D. Swanson <swannysec@users.noreply.github.com>
Follow-up to #49187.
Instead of silently skipping updates when `try_borrow_mut` fails, this
PR defers the update by spawning it on the foreground executor. This
ensures the state change is eventually processed after the current
borrow completes.
Release Notes:
- N/A
The `on_thermal_state_change` and `on_keyboard_layout_change` callbacks
in `App::new_app()` called `borrow_mut()` unconditionally. These
callbacks are invoked asynchronously by macOS via dispatch queues when
the system's thermal or keyboard state changes, which can happen while
the app's RefCell is already borrowed during an update cycle, causing a
panic.
This change uses `try_borrow_mut()` instead. If the borrow fails
(because the app is already borrowed), the callback silently skips the
update - the state can be queried on the next frame.
Fixes [ZED-4WM](https://zed-dev.sentry.io/issues/ZED-4WM)
Closes#49181
Release Notes:
- Fixed a crash on macOS caused by thermal or keyboard layout state
changes occurring during UI updates.
## Summary
- Adds a "Rules Hygiene" section to `.rules` after the existing Build
Guidelines section
- Establishes clear guidelines for when/how AI agents should propose
`.rules` changes
- Adds a "Crash Investigation" section with reference to
`script/crash-to-prompt` and other crash tooling
## What's in the Rules Hygiene section
**After any agentic session:** Agents should include a "Suggested .rules
additions" heading in their PR description if they discover non-obvious
patterns. Reviewers decide what gets merged.
**High bar for new rules:** Editing existing rules is always welcome.
New rules must be (1) non-obvious, (2) repeatedly encountered, and (3)
specific enough to act on. Single-crate rules go in that crate's
`.rules`.
**No drive-by additions:** Rules emerge from validated patterns through
a 3-step workflow: agent notes pattern → team validates → dedicated
commit.
## Context
Part of the Background Agent Pipeline initiative (BIZOPS-801). As we
scale automated crash investigation, we need guardrails to prevent
`.rules` bloat from agent sessions.
## Test plan
- [ ] Open a test agent session and confirm it sees the Rules Hygiene
guidance
- [ ] Verify the guidance is clear enough to follow without additional
context
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
## Summary
Reviewed and updated all 18 files in `docs/src/ai/` to meet Zed's brand
voice standards. Each file was scored against the 8-criterion rubric and
rewritten where needed to achieve 4+ on all criteria.
**Changes include:**
- Remove "Learn how to/about" patterns (8 instances)
- Replace vague phrases ("various types of tasks", "and more") with
specific examples
- Remove taboo words ("seamless", "naturally extends")
- Remove emotional language ("We're excited/thrilled/happy")
- Remove marketing patterns ("Stay tuned!", exclamation points)
- Remove unverifiable claims ("world's fastest")
- Replace hedging with direct statements
- Remove promotional emphasis (`_free_`, `**_for free_**`)
- Fix typo in external-agents.md ("servers" → "serves")
- Fix broken link syntax for Ollama Turbo
## Test plan
- [x] `mdbook build` succeeds
- [x] Grep for remaining taboo phrases (only one "seamless" in MCP
official quote, preserved intentionally)
- [x] All facts preserved (URLs, keybindings, settings keys, prices,
model names)
Fixes AI-8
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Documentation Update Summary
### Changes Made
| File | Change | Related Code |
| --- | --- | --- |
| `docs/src/ai/edit-prediction.md` | Updated Codestral setup
instructions to use Settings Editor path instead of outdated
`agent::OpenSettings` action reference | Settings Editor provider
configuration flow |
### Rationale
The primary documentation update addresses outdated instructions in the
Codestral setup section. The original text referenced an
`agent::OpenSettings` action that directed users to an "Agent Panel
settings view" which no longer reflects the current UI flow. The updated
instructions now guide users through the Settings Editor with
platform-specific keyboard shortcuts and provide an alternative status
bar path.
### Review Notes
- **Codestral instructions**: Reviewers should verify the Settings
Editor navigation path (`Cmd+,` → search "Edit Predictions" →
**Configure Providers**) matches the current Zed UI
- **Status bar alternative**: The alternative path via "edit prediction
icon in the status bar" should be confirmed as accurate
---
## Update from 2025-12-21 20:25
---
**Source**: [#44914](https://github.com/zed-industries/zed/pull/44914) -
settings_ui: Add Edit keybindings button
**Author**: @probably-neb
Now I have all the context needed to create a comprehensive
documentation update summary.
## Documentation Update Summary
### Changes Made
| File | Change | Related Code |
| --- | --- | --- |
| docs/src/ai/agent-panel.md | Added documentation for `agent::PasteRaw`
action, explaining automatic @mention formatting for pasted code and how
to bypass it | PR #45254 |
### Rationale
PR #45254 ("agent_ui: Improve UX when pasting code into message editor")
introduced the `agent::PasteRaw` action, which allows users to paste
clipboard content without automatic formatting. When users copy
multi-line code from an editor buffer and paste it into the Agent panel,
Zed now automatically formats it as an @mention with file context. The
`PasteRaw` action provides a way to bypass this behavior when raw text
is preferred.
This documentation update ensures users can discover both:
1. The new automatic @mention formatting behavior
2. The keybinding to bypass it when needed
### Review Notes
- The new paragraph was placed in the "Adding Context" section,
immediately after the existing note about image pasting support—this
maintains logical flow since both relate to pasting behavior
- Uses the standard `{#kb agent::PasteRaw}` syntax for keybinding
references, consistent with other keybinding documentation in the file
- The documentation passed Prettier formatting validation without
modifications
---
### Condensed Version (for commit message)
```
docs(agent-panel): Document PasteRaw action for bypassing auto @mention formatting
Added explanation that multi-line code pasted from editor buffers is
automatically formatted as @mentions, with keybinding to paste raw text.
Related: PR #45254
```
Release Notes:
- N/A
---------
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Zed Zippy <234243425+zed-zippy[bot]@users.noreply.github.com>
Stashes local changes before branch checkout in droid auto docs CLI
Release Notes:
- N/A
---------
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Droid needs a specific model with a date
Release Notes:
- N/A
---------
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Change from cli.factory.ai/install.sh to app.factory.ai/cli per official
Factory documentation.
Release Notes:
- N/A
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Adds a multi-step agentic loop to github actions for opening a
once-daily documentation PR that can be merged only be a Zedi
Release Notes:
- N/A
---------
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
### 1. **Added Tax ID Collection Types**
- Created a new `StripeTaxIdCollection` struct with an `enabled` field
- Added `tax_id_collection` field to `StripeCreateCheckoutSessionParams`
### 2. **Updated the Stripe Client Interface**
- Modified the real Stripe client to handle tax ID collection conversion
- Updated the fake Stripe client for testing purposes
- Added proper imports across all affected files
### 3. **Enabled Tax ID Collection in Checkout Sessions**
- Both `checkout_with_zed_pro` and `checkout_with_zed_pro_trial` methods
now enable tax ID collection
- The implementation correctly sets `tax_id_collection.enabled = true`
for all checkout sessions
### 4. **Key Implementation Details**
- Tax ID collection will be shown to new customers and existing
customers without tax IDs
- Collected tax IDs will be automatically saved to the customer's
`tax_ids` array in Stripe
- Business names will be saved to the customer's `name` property
- The existing `customer_update.name = auto` setting ensures
compatibility with tax ID collection
Release Notes:
- N/A
We are collecting billing address and name on checkout now (for tax) but
we're not saving it back to the Customer level. Updating the Checkout
Session code to make`customer_update.address` equal to `auto`, instead
of the default `never`, as well as the same for `customer_update.name`.
Release Notes:
- N/A
Summary
I've successfully implemented the required billing address collection
feature for Stripe Checkout sessions. Here's what was done:
### 1. **Added New Data Structures** (`stripe_client.rs`):
- Added `StripeBillingAddressCollection` enum with `Auto` and `Required`
variants
- Added `billing_address_collection` field to
`StripeCreateCheckoutSessionParams`
### 2. **Updated Stripe Client Implementation**
(`real_stripe_client.rs`):
- Added conversion from `StripeBillingAddressCollection` to Stripe's
`CheckoutSessionBillingAddressCollection`
- Updated the `TryFrom` implementation to map the billing address
collection field when creating checkout sessions
- Added the necessary import
### 3. **Updated Billing Service** (`stripe_billing.rs`):
- Set `billing_address_collection` to `Required` in both
`checkout_with_zed_pro()` and `checkout_with_zed_pro_trial()` methods
- Added the necessary import
### 4. **Updated Test Infrastructure** (`fake_stripe_client.rs`):
- Added `billing_address_collection` field to
`StripeCreateCheckoutSessionCall`
- Updated the `create_checkout_session` implementation to capture the
new field
- Added the necessary import
### 5. **Updated Tests** (`stripe_billing_tests.rs`):
- Added assertions to verify that `billing_address_collection` is set to
`Required` in all three test cases:
- `test_checkout_with_zed_pro`
- `test_checkout_with_zed_pro_trial` (regular trial)
- `test_checkout_with_zed_pro_trial` (extended trial)
- Added the necessary import
The implementation follows the pattern established in the codebase and
ensures that whenever a Stripe Checkout session is created for Zed Pro
subscriptions (both regular and trial), the billing address will be
required from customers. This aligns with the Stripe documentation you
provided, which shows that setting `billing_address_collection=required`
will ensure the billing address is always collected during checkout.
Release Notes:
- N/A
Co-authored-by: Marshall Bowers <git@maxdeviant.com>
morgankrey