docs: editing rules

packages/web/astro.config.mjs

@@ -73,8 +73,8 @@ export default defineConfig({
       sidebar: [
         "docs",
         "docs/cli",
+        "docs/rules",
         "docs/config",
-        "docs/agents",
         "docs/models",
         "docs/themes",
         "docs/keybinds",

packages/web/src/content/docs/docs/agents.mdx

@@ -1,45 +0,0 @@
----
-title: AGENTS.md
----
-
-You can provide custom instructions to opencode by creating an `AGENTS.md` file. This works similarly to CLAUDE.md or cursor rules files. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project or workflow.
-
-## File Locations
-
-The `AGENTS.md` files are read from the following locations:
-
-- **Globally** under `~/.config/opencode/AGENTS.md` (applied to all opencode sessions)
-- **Project-specific** as `AGENTS.md` in any directory (applied when working within that directory or its subdirectories)
-
-When opencode starts, it looks for `AGENTS.md` files by starting from the current directory and traversing up the directory tree.
-
-## File Precedence
-
-When both global and local `AGENTS.md` files exist, opencode combines their contents. All found files are processed together:
-
-1. **Local files** found by traversing up from the current directory
-2. **Global file** located at `~/.config/opencode/AGENTS.md`
-
-This allows you to set general preferences globally while adding project-specific instructions locally.
-
-## Example
-
-```markdown
-# SST v3 Monorepo Project
-
-This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
-
-## Project Structure
-- `packages/` - Contains all workspace packages (functions, core, web, etc.)
-- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
-- `sst.config.ts` - Main SST configuration with dynamic imports
-
-## Code Standards
-- Use TypeScript with strict mode enabled
-- Shared code goes in `packages/core/` with proper exports configuration
-- Functions go in `packages/functions/`
-- Infrastructure should be split into logical files in `infra/`
-
-## Monorepo Conventions
-- Import shared modules using workspace names: `@my-app/core/example`
-```

packages/web/src/content/docs/docs/rules.mdx

@@ -0,0 +1,74 @@
+---
+title: Rules
+---
+
+You can provide custom instructions to opencode by creating an `AGENTS.md` file. This is similar to `CLAUDE.md` or Cursor's rules. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project.
+
+---
+
+## Initialize
+
+To create a new `AGENTS.md` file, you can run the `/init` command in opencode.
+
+:::tip
+You should commit your project's `AGENTS.md` file to Git.
+:::
+
+This will scan your project and all its contents to understand what the project is about and generate an `AGENTS.md` file with it. This helps opencode to navigate the project better.
+
+If you have an existing `AGENTS.md` file, this will try to add to it.
+
+---
+
+## Example
+
+You can also just create this file manually. Here's an example of some things you can put into an `AGENTS.md` file.
+
+```markdown title="AGENTS.md"
+# SST v3 Monorepo Project
+
+This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
+
+## Project Structure
+- `packages/` - Contains all workspace packages (functions, core, web, etc.)
+- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
+- `sst.config.ts` - Main SST configuration with dynamic imports
+
+## Code Standards
+- Use TypeScript with strict mode enabled
+- Shared code goes in `packages/core/` with proper exports configuration
+- Functions go in `packages/functions/`
+- Infrastructure should be split into logical files in `infra/`
+
+## Monorepo Conventions
+- Import shared modules using workspace names: `@my-app/core/example`
+```
+
+We are adding project-specific instructions here and this will be shared across your team.
+
+---
+
+## Types
+
+opencode also supports reading the `AGENTS.md` file from multiple locations. And this serves different purposes.
+
+### Project
+
+The ones we have seen above, where the `AGENTS.md` is placed in the project root, are project-specific rules. These only apply when you are working in this directory or its sub-directories.
+
+### Global
+
+You can also have global rules in a `~/.config/opencode/AGENTS.md` file. This gets applied across all opencode sessions.
+
+Since this isn't committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow.
+
+---
+
+## Precedence
+
+So when opencode starts, it looks for:
+
+1. **Local files** by traversing up from the current directory
+2. **Global file** by checking `~/.config/opencode/AGENTS.md`
+
+If you have both global and project-specific rules, opencode will combine them together.