docs: clarify issue template requirements

CONTRIBUTING.md

@@ -16,17 +16,27 @@ The Kilo Community is [on Discord](https://kilo.ai/discord).
 
 ## Developing Kilo CLI
 
-- **Requirements:** Bun 1.3+
+- **Requirements:** Bun 1.3.10+
 - Install dependencies and start the dev server from the repo root:
 
   ```bash
   bun install
   bun dev
   ```
 
+### Developing the VS Code Extension
+
+Build and launch the extension in an isolated VS Code instance:
+
+```bash
+bun run extension        # Build + launch in dev mode
+```
+
+This auto-detects VS Code on macOS, Linux, and Windows. Override with `--app-path PATH` or `VSCODE_EXEC_PATH`. Use `--insiders` to prefer Insiders, `--workspace PATH` to open a specific folder, or `--clean` to reset cached state.
+
 ### Running against a different directory
 
-By default, `bun dev` runs Kilo CLI in the `packages/kilo-cli` directory. To run it against a different directory or repository:
+By default, `bun dev` runs Kilo CLI in the `packages/opencode` directory. To run it against a different directory or repository:
 
 ```bash
 bun dev <directory>
@@ -43,13 +53,13 @@ bun dev .
 To compile a standalone executable:
 
 ```bash
-./packages/kilo-cli/script/build.ts --single
+./packages/opencode/script/build.ts --single
 ```
 
 Then run it with:
 
 ```bash
-./packages/kilo-cli/dist/kilo-cli-<platform>/bin/kilo
+./packages/opencode/dist/@kilocode/cli-<platform>/bin/kilo
 ```
 
 Replace `<platform>` with your platform (e.g., `darwin-arm64`, `linux-x64`).
@@ -70,13 +80,68 @@ kilo serve           # Start headless API server
 kilo web             # Start server + open web interface
 ```
 
-### Pull Request Expectations
+### Testing with a local backend
+
+To point the CLI at a local backend (e.g., a locally running Kilo API server on port 3000), set the `KILO_API_URL` environment variable:
+
+```bash
+KILO_API_URL=http://localhost:3000 bun dev
+```
+
+This redirects all gateway traffic (auth, model listing, provider routing, profile, etc.) to your local server. The default is `https://api.kilo.ai`.
+
+There are also optional overrides for other services:
+
+| Variable                  | Default                          | Purpose                                   |
+| ------------------------- | -------------------------------- | ----------------------------------------- |
+| `KILO_API_URL`            | `https://api.kilo.ai`            | Kilo API (gateway, auth, models, profile) |
+| `KILO_SESSION_INGEST_URL` | `https://ingest.kilosessions.ai` | Session export / cloud sync               |
+| `KILO_MODELS_URL`         | `https://models.dev`             | Model metadata                            |
+
+> **VS Code:** The repo includes a "VSCode - Run Extension (Local Backend)" launch config in `.vscode/launch.json` that sets `KILO_API_URL=http://localhost:3000` automatically.
+
+## Issue Template Requirements
+
+If you open an issue through the GitHub web UI, GitHub will guide you through the correct template automatically.
+
+If you open an issue through `gh issue create`, the API, or another tool that bypasses the web UI, include the equivalent required fields yourself so the issue still matches the template.
+
+Current required fields by issue type:
+
+- **Bug report:** include a `Description`.
+- **Feature request:** include confirmation that the feature has not already been suggested, plus a description of the enhancement.
+- **Question:** include the `Question`.
+
+Recommended fields for bug reports, even when not strictly required by the template:
+
+- Plugins
+- Kilo version
+- Steps to reproduce
+- Screenshot and/or share link
+- Operating System
+- Terminal
+
+## Pull Request Expectations
 
 - **Issue First Policy:** All PRs must reference an existing issue.
 - **UI Changes:** Include screenshots or videos (before/after).
 - **Logic Changes:** Explain how you verified it works.
 - **PR Titles:** Follow conventional commit standards (`feat:`, `fix:`, `docs:`, etc.).
 
+## Issue First Policy
+
+All pull requests must reference an existing issue.
+
+This helps reviewers understand the problem statement, discussion, and intended scope before reviewing the code change.
+
+## PR Titles
+
+Use conventional commit style PR titles such as:
+
+- `fix: correct Windows path handling`
+- `docs: clarify issue template requirements`
+- `feat: add MCP settings tab`
+
 ### Issue and PR Lifecycle
 
 To keep our backlog manageable, we automatically close inactive issues and PRs after a period of inactivity. This isn't a judgment on quality — older items tend to lose context over time and we'd rather start fresh if they're still relevant. Feel free to reopen or create a new issue/PR if you're still working on something!