WIP New App Docs (#3624)

[[PR Description]]

These docs are intended to replace both docs.zed.dev and introduce
people to how to build Zed from source.

Add or edit markdown files in the docs/src folder, and follow the
instructions in `how-to-deploy.md` to deploy the docs on
[Vercel](https://vercel.com/zed-industries/zed-app-docs/45ZTNBKSCmCMAvfAcfcocGnmoMyd).

Add pages and organize/reorder docs in the SUMMARY.md.

When you are sure a page is added or is no longer needed you can delete
it from `docs/old`

Release Notes:

- N/A

docs/.gitignore

@@ -0,0 +1,2 @@
+book
+.vercel

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Nate Butler"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Zed App Docs"

docs/how-to-deploy.md

@@ -0,0 +1,10 @@
+These docs are intendended to replace both docs.zed.dev and introduce people to how to build Zed from source.
+
+1. `cd docs` from repo root
+1. Install the vercel cli if you haven't already
+    - `pnpm i -g vercel`
+1. `vercel` to deploy if you already have the project linked
+1. Otherwise, `vercel login` and `vercel` to link
+    - Choose Zed Industries as the team, then `zed-app-docs` as the project
+
+Someone can write a script for this when they have time.

docs/src/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hi@zed.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/src/SUMMARY.md

@@ -0,0 +1,25 @@
+# Summary
+
+[Getting Started](./getting_started.md)
+[Feedback](./feedback.md)
+
+# Configuring Zed
+- [Settings](./configuring_zed.md)
+- [Vim Mode](./configuring_zed__configuring_vim.md)
+
+# Using Zed
+- [Workflows]()
+- [Collaboration]()
+- [Using AI]()
+
+# Contributing to Zed
+- [How to Contribute]()
+- [Building from Source](./developing_zed__building_zed.md)
+- [Local Collaboration](./developing_zed__local_collaboration.md)
+- [Adding Languages](./developing_zed__adding_languages.md)
+- [Adding UI]()
+
+---
+
+[Telemetry](./telemetry.md)
+[Code of Conduct](./CODE_OF_CONDUCT.md)

docs/src/configuring_zed__configuring_vim.md

@@ -0,0 +1,170 @@
+# Vim Mode
+
+Zed includes a vim emulation layer known as “vim mode”. This document aims to describe how it works, and how to make the most out of it.
+
+### Philosophy
+Vim mode in Zed is supposed to primarily "do what you expect": it mostly tries to copy vim exactly, but will use Zed-specific functionality when available to make things smoother.
+
+This means Zed will never be 100% vim compatible, but should be 100% vim familiar! We expect that our vim mode already copes with 90% of your workflow, and we'd like to keep improving it. If you find things that you can’t yet do in vim mode, but which you rely on in your current workflow, please leave feedback in the editor itself (`:feedback`), or [file an issue](https://github.com/zed-industries/community).
+
+### Zed-specific features
+Zed is built on a modern foundation that (among other things) uses tree-sitter to understand the content of the file you're editing, and supports multiple cursors out of the box.
+
+Vim mode has several "core Zed" key bindings, that will help you make the most of Zed's specific feature set.
+```
+# Normal mode
+g d   Go to definition
+g D   Go to type definition
+c d   Rename (change definition)
+g A   Go to All references to the current word
+
+g <space>  Open the current search excerpt in its own tab
+
+g s   Find symbol in current file
+g S   Find symbol in entire project
+
+g n   Add a visual selection for the next copy of the current word
+g N   The same, but backwards
+g >   Skip latest word selection, and add next.
+g <   The same, but backwards
+g a   Add a visual selection for every copy of the current word
+
+g h   Show inline error (hover)
+
+# Insert mode
+ctrl-x ctrl-o  Open the completion menu
+ctrl-x ctrl-c  Request Github Copilot suggestion (if configured)
+ctrl-x ctrl-a  Open the inline AI assistant (if configured)
+ctrl-x ctrl-l  Open the LSP code actions
+ctrl-x ctrl-z  Hides all suggestions
+```
+
+Vim mode uses Zed to define concepts like "brackets" (for the `%` key) and "words" (for motions like `w` and `e`). This does lead to some differences, but they are mostly positive. For example `%` considers `|` to be a bracket in languages like Rust; and `w` considers `$` to be a word-character in languages like Javascript.
+
+Vim mode emulates visual block mode using Zed's multiple cursor support. This again leads to some differences, but is much more powerful.
+
+Finally, Vim mode's search and replace functionality is backed by Zed's. This means that the pattern syntax is slightly different, see the section on [Regex differences](#regex-differences) for details.
+
+### Custom key bindings
+Zed does not yet have an equivalent to vim’s `map` command to convert one set of keystrokes into another, however you can bind any sequence of keys to fire any Action documented in the  [Key bindings documentation](https://docs.zed.dev/configuration/key-bindings).
+
+You can edit your personal key bindings with `:keymap`.
+For vim-specific shortcuts, you may find the following template a good place to start:
+
+```json
+[
+  {
+    "context": "Editor && VimControl && !VimWaiting && !menu",
+    "bindings": {
+      // put key-bindings here if you want them to work in normal & visual mode
+    }
+  },
+  {
+    "context": "Editor && vim_mode == normal && !VimWaiting && !menu",
+    "bindings": {
+      // put key-bindings here if you want them to work only in normal mode
+    }
+  },
+  {
+    "context": "Editor && vim_mode == visual && !VimWaiting && !menu",
+    "bindings": {
+      // visual, visual line & visual block modes
+    }
+  },
+  {
+    "context": "Editor && vim_mode == insert && !menu",
+    "bindings": {
+      // put key-bindings here if you want them to work in insert mode
+    }
+  }
+]
+```
+
+You can see the bindings that are enabled by default in vim mode [here](https://zed.dev/ref/vim.json).
+
+The details of the context are a little out of scope for this doc, but suffice to say that `menu` is true when a menu is open (e.g. the completions menu), `VimWaiting` is true after you type `f` or `t` when we’re waiting for a new key (and you probably don’t want bindings to happen). Please reach out on [Github](https://github.com/zed-industries/community) if you want help making a key bindings work.
+
+### Command palette
+
+Vim mode allows you to enable Zed’s command palette with `:`. This means that you can use vim's command palette to run any action that Zed supports.
+
+Additionally vim mode contains a number of aliases for popular vim commands to ensure that muscle memory works. For example `:w<enter>` will save the file.
+
+We do not (yet) emulate the full power of vim’s command line, in particular we special case specific patterns instead of using vim's range selection syntax, and we do not support arguments to commands yet. Please reach out on [Github](https://github.com/zed-industries/community) as you find things that are missing from the command palette.
+
+As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
+
+Currently supported vim-specific commands (as of Zed 0.106):
+```
+# window management
+:w[rite][!], :wq[!], :q[uit][!], :wa[ll][!], :wqa[ll][!], :qa[ll][!], :[e]x[it][!], :up[date]
+    to save/close tab(s) and pane(s) (no filename is supported yet)
+:cq
+    to quit completely.
+:vs[plit], :sp[lit]
+    to split vertically/horizontally (no filename is supported yet)
+:new, :vne[w]
+    to create a new file in a new pane above or to the left
+:tabedit, :tabnew
+    to create a new file in a new tab.
+:tabn[ext], :tabp[rev]
+    to go to previous/next tabs
+:tabc[lose]
+    to close the current tab
+
+# navigating diagnostics
+:cn[ext], :cp[rev], :ln[ext], :lp[rev]
+    to go to the next/prev diagnostics
+:cc, :ll
+    to open the errors page
+
+# jump to position
+:<number>
+    to jump to a line number
+:$
+    to jump to the end of the file
+:/foo and :?foo
+    to jump to next/prev line matching foo
+
+# replacement
+:%s/foo/bar/
+    to replace instances of foo with bar (/g is always assumed, the range must always be %, and Zed uses different regex syntax to vim)
+
+# editing
+:j[oin]
+    to join the current line (no range is yet supported)
+:d[elete][l][p]
+    to delete the current line (no range is yet supported)
+:s[ort] [i]
+    to sort the current selection (with i, case-insensitively)
+```
+
+
+### Related settings
+There are a few Zed settings that you may also enjoy if you use vim mode:
+```
+{
+  // disable cursor blink
+  "cursor_blink": false
+  // use relative line numbers
+  "relative_line_numbers": true,
+  // hide the scroll bar
+  "scrollbar": {"show": "never"},
+}
+```
+
+### Regex differences
+
+Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
+
+Notably:
+* Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
+* On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
+* When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
+* Vim uses `\<` and `\>` to represent word boundaries, in Zed these are both handled by `\b`
+* Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
+* Vim uses `/i` to indicate "case-insensitive", in Zed you can either use `(?i)` at the start of the pattern or toggle case-sensitivity with `cmd-option-c`.
+
+To help with the transition, the command palette will fix parentheses and replace groups for you when you run `:%s//`. So `%s:/\(a\)(b)/\1/` will be converted into a search for "(a)\(b\)" and a replacement of "$1".
+
+For the full syntax supported by Zed's regex engine see the [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).

docs/src/developing_zed__adding_languages.md

@@ -0,0 +1,83 @@
+# Adding New Languages to Zed
+
+## LSP
+
+Zed uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) to provide language support. This means, in theory, we can support any language that has an LSP server.
+
+## Syntax Highlighting
+
+### Defining syntax highlighting rules
+
+We use tree-sitter queries to match certian properties to highlight.
+
+#### Simple Example:
+
+```scheme
+(property_identifier) @property
+```
+
+```ts
+const font: FontFamily = {
+    weight: "normal",
+    underline: false,
+    italic: false,
+}
+```
+
+Match a property identifier and highlight it using the identifier `@property`. In the above example, `weight`, `underline`, and `italic` would be highlighted.
+
+#### Complex example:
+
+```scheme
+(_
+  return_type: (type_annotation
+    [
+      (type_identifier) @type.return
+      (generic_type
+          name: (type_identifier) @type.return)
+    ]))
+```
+
+```ts
+function buildDefaultSyntax(colorScheme: Theme): Partial<Syntax> {
+    // ...
+}
+```
+
+Match a function return type, and highlight the type using the identifier `@type.return`. In the above example, `Partial` would be highlighted.
+
+#### Example - Typescript
+
+Here is an example portion of our `highlights.scm` for TypeScript:
+
+```scheme
+; crates/zed/src/languages/typescript/highlights.scm
+
+; Variables
+
+(identifier) @variable
+
+; Properties
+
+(property_identifier) @property
+
+; Function and method calls
+
+(call_expression
+  function: (identifier) @function)
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @function.method))
+
+; Function and method definitions
+
+(function
+  name: (identifier) @function)
+(function_declaration
+  name: (identifier) @function)
+(method_definition
+  name: (property_identifier) @function.method)
+
+; ...
+```

docs/src/developing_zed__building_zed.md

@@ -0,0 +1,107 @@
+# Building Zed
+
+🚧 TODO:
+- [ ] Tidy up & update instructions
+- [ ] Remove ZI-specific things
+- [ ] Rework any steps that currently require a ZI-specific account
+
+How to build Zed from source for the first time.
+
+## Prerequisites
+
+- Be added to the GitHub organization
+- Be added to the Vercel team
+
+## Process
+
+Expect this to take 30min to an hour! Some of these steps will take quite a while based on your connection speed, and how long your first build will be.
+
+1. Install the [GitHub CLI](https://cli.github.com/):
+   - `brew install gh`
+1. Clone the `zed` repo
+   - `gh repo clone zed-industries/zed`
+1. Install Xcode from the macOS App Store
+1. Install Xcode command line tools
+   - `xcode-select --install`
+   - If xcode-select --print-path prints /Library/Developer/CommandLineTools… run `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.`
+1. Install [Postgres](https://postgresapp.com)
+1. Install rust/rustup
+   - `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+1. Install the wasm toolchain
+   - `rustup target add wasm32-wasi`
+1. Install Livekit & Foreman
+   - `brew install livekit`
+   - `brew install foreman`
+1. Generate an GitHub API Key
+   - Go to https://github.com/settings/tokens and Generate new token
+   - GitHub currently provides two kinds of tokens:
+     - Classic Tokens, where only `repo` (Full control of private repositories) OAuth scope has to be selected
+       Unfortunately, unselecting `repo` scope and selecting every its inner scope instead does not allow the token users to read from private repositories
+     - (not applicable) Fine-grained Tokens, at the moment of writing, did not allow any kind of access of non-owned private repos
+   - Keep the token in the browser tab/editor for the next two steps
+1. (Optional but reccomended) Add your GITHUB_TOKEN to your `.zshrc` or `.bashrc` like this: `export GITHUB_TOKEN=yourGithubAPIToken`
+1. Ensure the Zed.dev website is checked out in a sibling directory and install it's dependencies:
+    ```
+    cd ..
+    git clone https://github.com/zed-industries/zed.dev
+    cd zed.dev && npm install
+    npm install -g vercel
+    ```
+1. Link your zed.dev project to Vercel
+    - `vercel link`
+    - Select the `zed-industries` team. If you don't have this get someone on the team to add you to it.
+    - Select the `zed.dev` project
+1. Run `vercel pull` to pull down the environment variables and project info from Vercel
+1. Open Postgres.app
+1. From `./path/to/zed/`:
+    - Run:
+        - `GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap`
+        - Replace `{yourGithubAPIToken}` with the API token you generated above.
+        - You don't need to include the GITHUB_TOKEN if you exported it above.
+    - Consider removing the token (if it's fine for you to recreate such tokens during occasional migrations) or store this token somewhere safe (like your Zed 1Password vault).
+   - If you get:
+     - ```bash
+       Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
+       Please create a new installation in /opt/homebrew using one of the
+       "Alternative Installs" from:
+       https://docs.brew.sh/Installation
+       ```
+     - In that case try:
+       - `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+   - If Homebrew is not in your PATH:
+     - Replace `{username}` with your home folder name (usually your login name)
+     - `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile`
+     - `eval "$(/opt/homebrew/bin/brew shellenv)"`
+1. To run the Zed app:
+    - If you are working on zed:
+      - `cargo run`
+    - If you are just using the latest version, but not working on zed:
+      - `cargo run --release`
+    - If you need to run the collaboration server locally:
+      - `script/zed-local`
+
+## Troubleshooting
+
+### `error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`
+
+- Try `xcode-select --switch /Applications/Xcode.app/Contents/Developer`
+
+### `xcrun: error: unable to find utility "metal", not a developer tool or in PATH`
+
+### Seeding errors during `script/bootstrap` runs
+
+```
+seeding database...
+thread 'main' panicked at 'failed to deserialize github user from 'https://api.github.com/orgs/zed-industries/teams/staff/members': reqwest::Error { kind: Decode, source: Error("invalid type: map, expected a sequence", line: 1, column: 0) }', crates/collab/src/bin/seed.rs:111:10
+```
+
+Wrong permissions for `GITHUB_TOKEN` token used, the token needs to be able to read from private repos.
+For Classic GitHub Tokens, that required OAuth scope `repo` (seacrh the scope name above for more details)
+
+Same command
+
+`sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
+
+### If you experience errors that mention some dependency is using unstable features
+
+Try `cargo clean` and `cargo build`

docs/src/developing_zed__local_collaboration.md

@@ -0,0 +1,22 @@
+# Local Collaboration
+
+## Setting up the local collaboration server
+
+### Setting up for the first time?
+
+1. Make sure you have livekit installed (`brew install livekit`)
+1. Install [Postgres](https://postgresapp.com) and run it.
+1. Then, from the root of the repo, run `script/bootstrap`.
+
+### Have a db that is out of date? / Need to migrate?
+
+1. Make sure you have livekit installed (`brew install livekit`)
+1. Try `cd crates/collab && cargo run -- migrate` from the root of the repo.
+1. Run `script/seed-db`
+
+## Testing collab locally
+
+1. Run `foreman start` from the root of the repo.
+1. In another terminal run `script/zed-local -2`.
+1. Two copies of Zed will open. Add yourself as a contact in the one that is not you.
+1. Start a collaboration session as normal with any open project.

docs/src/feedback.md

@@ -0,0 +1,29 @@
+# Giving feedback
+
+### Community repository
+
+We track our issues at [`zed-industries/community`](https://github.com/zed-industries/community/issues).
+
+#### Feature requests
+
+Try to focus on the things that are most critical to you rather than exhaustively listing all features another editor you have used has.
+
+Command palette: `request feature`
+
+#### Bug reports
+
+Try to add as much detail as possible, if it is not obvious to reproduce. Let us know how severe the problem is for you; is the issue more of a minor inconvenience or something that would prevent you from using Zed?
+
+Command palette: `file bug report`
+
+### In-app feedback
+
+Anonymous feedback can be submitted from within Zed via the feedback editor (command palette: `give feedback`).
+
+### Zed forum
+
+Use the [community forum](https://github.com/zed-industries/community/discussions) to ask questions and learn from one another. We will be present in the forum and answering questions as well.
+
+### Email
+
+If you prefer to write up your thoughts as an email, you can send them to [hi@zed.dev](mailto:hi@zed.dev).

docs/src/getting_started.md

@@ -0,0 +1,15 @@
+# Getting Started
+
+Welcome to Zed! We are excited to have you. Here is a jumping-off point to getting started.
+
+### Download Zed
+
+You can obtain the release build via the [download page](https://zed.dev/download). After the first manual installation, Zed will periodically check for and install updates automatically for you.
+
+### Configure Zed
+
+Use `CMD + ,` to open your custom settings to set things like fonts, formatting settings, per-language settings and more. You can access the default configuration using the `Zed > Settings > Open Default Settings` menu item. See Configuring Zed for all available settings.
+
+### Set up your key bindings
+
+You can access the default key binding set using the `Zed > Settings > Open Default Key Bindings` menu item. Use `CMD + K`,`CMD + S` to open your custom keymap to add your own key bindings. See Key Bindings for more info.,

docs/src/system_requirements.md

@@ -0,0 +1,13 @@
+# System Requirements
+
+## macOS
+
+Supported versions: Catalina (10.15) - Ventura (13.x).
+
+{% hint style="info" %}
+The implementation of our screen sharing feature makes use of [LiveKit](https://livekit.io). The LiveKit SDK requires macOS Catalina (10.15); consequently, in v0.62.4, we dropped support for earlier macOS versions that we were initially supporting.
+{% endhint %}
+
+## Linux, Windows, and Web
+
+_Not supported at this time. See our_ [_Platform Support_](https://github.com/zed-industries/community/issues/174) _issue._

docs/src/telemetry.md

@@ -0,0 +1,147 @@
+# Telemetry in Zed
+
+**Up to date with v0.112.0**
+
+Zed collects anonymous telemetry data to help the team understand how people are using the application and to see what sort of issues they are experiencing.
+
+## Dataflow
+
+Telemetry is sent from the application to zed.dev. Data is proxied through our servers to enable us to easily switch analytics services; we never store this data. The data is then sent off to various services:
+
+- [Datadog](https://www.datadoghq.com): Cloud-monitoring service - stores diagnostic events
+- [Clickhouse](https://clickhouse.com): Business Intelligence platform - stores both diagnostic and metric events
+- [Metabase](https://www.metabase.com): Dashboards - dashboards built around data pulled from Clickhouse
+
+## Types of Telemetry
+
+### Diagnostics
+
+Diagnostic events include debug information (stack traces) from crash reports. Reports are sent on the first application launch after the crash occurred. We've built dashboards that allow us to visualize the frequency and severity of issues experienced by users. Having these reports sent automatically allows us to begin implementing fixes without the user needing to file a report in our issue tracker. The plots in the dashboards also give us an informal measurement of the stability of Zed.
+
+When a panic occurs, the following data is sent:
+
+#### PanicRequest
+
+- `panic`: The panic data
+- `token`: An identifier that is used to authenticate the request on zed.dev
+
+#### Panic
+
+- `thread`: The name of the thread that panicked
+- `payload`: The panic message
+- `location_data`: The location of the panic
+    - `file`
+    - `line`
+- `backtrace`: The backtrace of the panic
+- `app_version`: Zed's app version
+- `release_channel`: Zed's release channel
+    - `stable`
+    - `preview`
+    - `dev`
+- `os_name`: The name of your operating system
+- `os_version`: The version of your operating system
+- `architecture`: The architecture of your CPU
+- `panicked_on`: The time that the panic occurred
+- `installation_id`: An identifier that is unique to each installation of Zed (this differs for stable, preview, and dev builds)
+- `session_id`: An identifier that is unique to each Zed session (this differs for each time you open Zed)
+
+### Metrics
+
+Zed also collects metric information based on user actions. Metric events are reported over HTTPS, and requests are rate-limited to avoid using significant network bandwidth. All data remains anonymous, and can't be related to specific Zed users.
+
+The following data is sent:
+
+#### ClickhouseEventRequestBody
+
+- `token`: An identifier that is used to authenticate the request on zed.dev
+- `installation_id`: An identifier that is unique to each installation of Zed (this differs for stable, preview, and dev builds)
+- `session_id`: An identifier that is unique to each Zed session (this differs for each time you open Zed)
+- `is_staff`: A boolean that indicates whether the user is a member of the Zed team or not
+- `app_version`: Zed's app version
+- `os_name`: The name of your operating system
+- `os_version`: The version of your operating system
+- `architecture`: The architecture of your CPU
+- `release_channel`: Zed's release channel
+    - `stable`
+    - `preview`
+    - `dev`
+- `events`: A vector of `ClickhouseEventWrapper`s
+
+#### ClickhouseEventWrapper
+
+- `signed_in`: A boolean that indicates whether the user is signed in or not
+- `event`: An enum, where each variant can be one of the following `ClickhouseEvent` variants:
+
+#### ClickhouseEvent
+
+- `editor`
+    - `operation`: The editor operation that was performed
+        - `open`
+        - `save`
+    - `file_extension`: The extension of the file that was opened or saved
+    - `vim_mode`: A boolean that indicates whether the user is in vim mode or not
+    - `copilot_enabled`: A boolean that indicates whether the user has copilot enabled or not
+    - `copilot_enabled_for_language`: A boolean that indicates whether the user has copilot enabled for the language of the file that was opened or saved
+    - `milliseconds_since_first_event`: Duration of time between this event's timestamp and the timestamp of the first event in the current batch
+- `copilot`
+    - `suggestion_id`: The ID of the suggestion
+    - `suggestion_accepted`: A boolean that indicates whether the suggestion was accepted or not
+    - `file_extension`: The file extension of the file that was opened or saved
+    - `milliseconds_since_first_event`: Same as above
+- `call`
+    - `operation`: The call operation that was performed
+        - `accept incoming`
+        - `decline incoming`
+        - `disable microphone`
+        - `disable screen share`
+        - `enable microphone`
+        - `enable screen share`
+        - `hang up`
+        - `invite`
+        - `join channel`
+        - `open channel notes`
+        - `share project`
+        - `unshare project`
+    - `room_id`: The ID of the room
+    - `channel_id`: The ID of the channel
+    - `milliseconds_since_first_event`: Same as above
+- `assistant`
+    - `conversation_id`: The ID of the conversation (for panel events only)
+    - `kind`: An enum with the following variants:
+        - `panel`
+        - `inline`
+    - `model`: The model that was used
+    - `milliseconds_since_first_event`: Same as above
+- `cpu`
+    - `usage_as_percentage`: The CPU usage
+    - `core_count`: The number of cores on the CPU
+    - `milliseconds_since_first_event`: Same as above
+- `memory`
+    - `memory_in_bytes`: The amount of memory used in bytes
+    - `virtual_memory_in_bytes`: The amount of virtual memory used in bytes
+    - `milliseconds_since_first_event`: Same as above
+- `app`
+    - `operation`: The app operation that was performed
+        - `first open`
+        - `open`
+        - `close (only in GPUI2-powered Zed)`
+    - `milliseconds_since_first_event`: Same as above
+
+You can audit the metrics data that Zed has reported by running the command `zed: open telemetry log` from the command palette, or clicking `Help > View Telemetry Log` in the application menu.
+
+### Configuring Telemetry Settings
+
+You have full control over what data is sent out by Zed. To enable or disable some or all telemetry types, open your `settings.json` file via `zed: open settings` from the command palette. Insert and tweak the following:
+
+```json
+"telemetry": {
+    "diagnostics": false,
+    "metrics": false
+},
+```
+
+The telemetry settings can also be configured via the `welcome` screen, which can be invoked via the `workspace: welcome` action in the command palette.
+
+### Concerns and Questions
+
+If you have concerns about telemetry, please feel free to open issues in our [community repository](https://github.com/zed-industries/community/issues/new/choose).