Rewrite product prose and local path/command examples across the docs
to match the shipped application (gwen CLI, Gwen config paths, Gwen.app,
com.yrkaierx.Gwen). Upstream distribution channels, service URLs and
package identifiers stay factually intact.
## What
`docs/.conventions/brand-voice/SKILL.md` declares:
```yaml
name: brand-writer
```
while sitting in a directory called `brand-voice`.
The Agent Skills specification requires the two to be identical:
> The required `name` field: … **Must match the parent directory name**
> — <https://agentskills.io/specification#name-field>
So this skill fails `skills-ref validate` today.
## Which side is wrong
The directory — and this repository settles it three separate ways, with
no outside context needed.
**1. The sibling copy already uses the matching name.**
`.factory/skills/brand-writer/` holds the same four files (`SKILL.md`,
`rubric.md`, `taboo-phrases.md`, `voice-examples.md`) under
`brand-writer`.
**2. `crates/agent_skills/README.md` documents the skill system using
this exact skill, and the name it documents is `brand-writer`:**
```
line 107: <name>brand-writer</name>
line 149: the model … calls `skill { name: "brand-writer" }`
line 151: when the user types `/brand-writer`
line 158: <skill_content name="brand-writer">
```
That name is load-bearing — it is what the skill tool invokes and what
the slash command types. The directory name is referenced twice, both
inside `docs/.conventions/CONVENTIONS.md`.
**3. Six of the repository's seven skills already match their
directory:**
| skill | matches? |
| --- | --- |
| `.agents/skills/gpui-test` | ✅ |
| `.agents/skills/lint-creator` | ✅ |
| `.agents/skills/zed-cherry-pick` | ✅ |
| `.factory/skills/brand-writer` | ✅ |
| `.factory/skills/humanizer` | ✅ |
| `crates/agent_skills/builtin/create-skill` | ✅ |
| **`docs/.conventions/brand-voice`** | ❌ the only one |
## The change
The frontmatter is untouched. Only the directory moves, plus the two
references to it:
- `docs/.conventions/brand-voice/` → `docs/.conventions/brand-writer/`
(4 files, pure rename)
- `CONVENTIONS.md:5` — `[brand-voice/](./brand-voice/)` →
`[brand-writer/](./brand-writer/)`
- `CONVENTIONS.md:368` — `` `brand-voice/rubric.md` `` → ``
`brand-writer/rubric.md` ``
`git grep brand-voice` returns nothing afterwards.
If you would rather keep the directory name and rename the field to
`brand-voice`, that is a one-line change instead and I am happy to
switch it — but it would give the two copies of one skill two different
names, and it would diverge from the name
`crates/agent_skills/README.md` documents.
## One thing I noticed but did not touch
The two copies have drifted. `.factory/skills/brand-writer/SKILL.md` is
279 lines and includes a *"Phase 4: Humanizer Pass"* section;
`docs/.conventions/`'s copy is 265 lines, lacks that section, and
renumbers Validation from Phase 5 to Phase 4. That is a separate
question about which copy is canonical, so it is left alone here.
---
Found with [AgentCompass](https://github.com/YoavLax/agent-compass), an
offline static analyzer for AI-agent repo readiness. Verified by hand
against the spec before opening.
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
Self-Review Checklist:
- [ ] I've reviewed my own diff for quality, security, and reliability
- [ ] Unsafe blocks (if any) have justifying comments
- [ ] The content is consistent with the [UI/UX
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
- [ ] Tests cover the new/changed behavior
- [ ] Performance impact has been considered and is acceptable
Change the actions in docs to adopt the right format.
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
yenru0
Bechor Simhaev