docs: add tutorial closes #740

2 files changed, 209 insertions, 53 deletions

diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx
index 615924616..102f1ca23 100644
--- a/packages/web/src/content/docs/docs/cli.mdx
+++ b/packages/web/src/content/docs/docs/cli.mdx
@@ -60,7 +60,7 @@ opencode auth [command]
 
 #### login
 
-Logs you into a provider and saves them in the credentials file in `~/.local/share/opencode/auth.json`.
+opencode is powered by the provider list at [Models.dev](https://models.dev), so you can use `opencode auth login` to configure API keys for any provider you'd like to use. This is stored in `~/.local/share/opencode/auth.json`.
 
 ```bash
 opencode auth login
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index 0484e9b3f..b96f773b1 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -5,73 +5,74 @@ description: Get started with opencode.
 
 import { Tabs, TabItem } from "@astrojs/starlight/components"
 
-[**opencode**](/) is an AI coding agent built for the terminal. It features:
-
-- A responsive, native, themeable terminal UI.
-- Automatically loads the right LSPs, so the LLMs make fewer mistakes.
-- Have multiple agents working in parallel on the same project.
-- Create shareable links to any session for reference or to debug.
-- Log in with Anthropic to use your Claude Pro or Claude Max account.
-- Supports 75+ LLM providers through [Models.dev](https://models.dev), including local models.
+[**opencode**](/) is an AI coding agent built for the terminal.
 
 ![opencode TUI with the opencode theme](../../../assets/lander/screenshot.png)
 
+Let's start by installing opencode.
+
 ---
 
 ## Install
 
-<Tabs>
-  <TabItem label="npm">
-    ```bash
-    npm install -g opencode-ai
-    ```
-  </TabItem>
-  <TabItem label="Bun">
-    ```bash
-    bun install -g opencode-ai
-    ```
-  </TabItem>
-  <TabItem label="pnpm">
-    ```bash
-    pnpm install -g opencode-ai
-    ```
-  </TabItem>
-  <TabItem label="Yarn">
-    ```bash
-    yarn global add opencode-ai
-    ```
-  </TabItem>
-</Tabs>
-
-You can also install the opencode binary through the following.
-
-##### Using the install script
+The easiest way to install opencode is through the install script.
 
 ```bash
 curl -fsSL https://opencode.ai/install | bash
 ```
 
-##### Using Homebrew on macOS
-
-```bash
-brew install sst/tap/opencode
-```
-
-##### Using Paru on Arch Linux
-
-```bash
-paru -S opencode-bin
-```
-
-##### Windows
+You can also install it with the following:
+
+- **Using Node.js**
+
+  <Tabs>
+    <TabItem label="npm">
+      ```bash
+      npm install -g opencode-ai
+      ```
+    </TabItem>
+    <TabItem label="Bun">
+      ```bash
+      bun install -g opencode-ai
+      ```
+    </TabItem>
+    <TabItem label="pnpm">
+      ```bash
+      pnpm install -g opencode-ai
+      ```
+    </TabItem>
+    <TabItem label="Yarn">
+      ```bash
+      yarn global add opencode-ai
+      ```
+    </TabItem>
+  </Tabs>
+
+- **Using Homebrew on macOS**
+
+  ```bash
+  brew install sst/tap/opencode
+  ```
+
+- **Using Paru on Arch Linux**
+
+  ```bash
+  paru -S opencode-bin
+  ```
+
+#### Windows
 
 Right now the automatic installation methods do not work properly on Windows. However you can grab the binary from the [Releases](https://github.com/sst/opencode/releases).
 
 ---
 
-## Providers
+## Configure
+
+With opencode you can use any LLM provider by configuring their API keys.
+
+We recommend signing up for [Claude Pro](https://www.anthropic.com/news/claude-pro) or [Max](https://www.anthropic.com/max), it's the most cost-effective way to use opencode.
 
-We recommend signing up for Claude Pro or Max, running `opencode auth login` and selecting Anthropic. It's the most cost-effective way to use opencode.
+Once you've singed up, run `opencode auth login` and select Anthropic.
 
 ```bash
 $ opencode auth login
@@ -90,8 +91,163 @@ $ opencode auth login
 └
 ```
 
-opencode is powered by the provider list at [Models.dev](https://models.dev), so you can use `opencode auth login` to configure API keys for any provider you'd like to use. This is stored in `~/.local/share/opencode/auth.json`.
+Alternatively, you can select one of the other providers and adding their API keys.
+
+---
+
+## Initialize
+
+Now that you've configured a provider, you can navigate to a project that
+you want to work on.
+
+```bash
+cd /path/to/project
+```
+
+And run opencode.
+
+```bash
+opencode
+```
+
+Next, initialize opencode for the project by running the following command.
+
+```bash frame="none"
+/init
+```
+
+This will get opencode to analyze your project and create an `AGENTS.md` file in
+the project root.
+
+:::tip
+You should commit your project's `AGENTS.md` file to Git.
+:::
+
+This helps opencode understand the project structure and the coding patterns
+used. 
+
+---
+
+## Usage
+
+You are now ready to use opencode to work on your project. Feel free to ask it
+anything!
+
+If you are new to using an AI coding agent, here are some examples that might
+help.
+
+---
+
+### Ask questions
+
+You can ask opencode to explain the codebase to you.
+
+```txt frame="none"
+How is authentication handled in @packages/functions/src/api/index.ts
+```
+
+This is helpful if there's a part of the codebase that you didn't work on.
+
+:::tip
+Use the `@` key to fuzzy search for files in the project.
+:::
+
+---
+
+### Add features
+
+You can ask opencode to add new features to your project. Though we first recommend asking it to create a plan.
+
+1. **Create a plan**
+
+   opencode has a _Plan mode_ that disables its ability to make changes and
+   instead suggest _how_ it'll implement the feature.
+
+   Switch to it using the **Tab** key. You'll see an indicator for this in the lower right corner.
+   
+   ```bash frame="none" title="Switch to Plan mode"
+   <TAB>
+   ```
+
+   Now let's describe what we want it to do.
+   
+   ```txt frame="none"
+   When a user deletes a note, we'd like to flag it as deleted in the database.
+   Then create a screen that shows all the recently deleted notes.
+   From this screen, the user can undelete a note or permanently delete it.
+   ```
+   
+   You want to give opencode enough details to understand what you want. It helps
+   to talk to it like you are talking to a junior developer on your team.
+   
+   :::tip
+   Give opencode plenty of context and examples to help it understand what you
+   want.
+   :::
+
+2. **Iterate on the plan**
+
+   Once it gives you a plan, you can give it feedback or add more details.
+   
+   ```txt frame="none"
+   We'd like to design this new screen using the design we are already using.
+   There's an example of a list of notes in @packages/web/src/components/NoteList.tsx
+   ```
+
+3. **Build the feature**
+   
+   Once you feel comfortable with the plan, switch back to _Build mode_ by
+   hitting the **Tab** key again.
+   
+   ```bash frame="none"
+   <TAB>
+   ```
+   
+   And asking it to make the changes.
+   
+   ```bash frame="none"
+   Sounds good! Go ahead and make the changes.
+   ```
+
+---
+
+### Make changes
+
+For more straightforward changes, you can ask opencode to directly build it
+without having to review the plan first.
+
+```txt frame="none"
+We need to add authentication to the /settings route. Take a look at how this is
+handled in the /notes route in @packages/functions/src/notes.ts and implement
+the same logic in @packages/functions/src/settings.ts
+```
+
+You want to make sure you provide a good amount of detail so opencode makes the right
+changes.
+
+---
+
+## Share
+
+The conversations that you have with opencode can be [shared with your
+team](/docs/share).
+
+```bash frame="none"
+/share
+```
+
+This'll create a link to the current conversation and copy it to your clipboard.
+
+:::note
+Conversations are not shared by default.
+:::
+
+Here's an [example conversation](https://opencode.ai/s/4XP1fce5) with opencode.
+
+---
+
+## Customize
 
-The Models.dev dataset is also used to detect common environment variables like `OPENAI_API_KEY` to autoload that provider.
+And that's it! You are now a pro at using opencode.
 
-If there are additional providers you want to use you can submit a PR to the [Models.dev repo](https://github.com/sst/models.dev). You can also [add them to your config](/docs/config) for yourself.
+To make it your own, we recommend [picking a theme](/docs/themes), [customizing the keybinds](/docs/keybinds), or playing around with the [opencode config](/docs/config).