@neocode-ai/web 1.1.1

package/src/content/docs/troubleshooting.mdx

@@ -0,0 +1,300 @@
+---
+title: Troubleshooting
+description: Common issues and how to resolve them.
+---
+
+To debug issues with NeoCode, start by checking the logs and local data it stores on disk.
+
+---
+
+## Logs
+
+Log files are written to:
+
+- **macOS/Linux**: `~/.local/share/neocode/log/`
+- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\neocode\log`
+
+Log files are named with timestamps (e.g., `2025-01-09T123456.log`) and the most recent 10 log files are kept.
+
+You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `neocode --log-level DEBUG`.
+
+---
+
+## Storage
+
+neocode stores session data and other application data on disk at:
+
+- **macOS/Linux**: `~/.local/share/neocode/`
+- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\neocode`
+
+This directory contains:
+
+- `auth.json` - Authentication data like API keys, OAuth tokens
+- `log/` - Application logs
+- `project/` - Project-specific data like session and message data
+  - If the project is within a Git repo, it is stored in `./<project-slug>/storage/`
+  - If it is not a Git repo, it is stored in `./global/storage/`
+
+---
+
+## Desktop app
+
+NeoCode Desktop runs a local NeoCode server (the `neocode-cli` sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
+
+### Quick checks
+
+- Fully quit and relaunch the app.
+- If the app shows an error screen, click **Restart** and copy the error details.
+- macOS only: `NeoCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
+
+---
+
+### Disable plugins
+
+If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.
+
+#### Check the global config
+
+Open your global config file and look for a `plugin` key.
+
+- **macOS/Linux**: `~/.config/neocode/neocode.jsonc` (or `~/.config/neocode/neocode.json`)
+- **macOS/Linux** (older installs): `~/.local/share/neocode/neocode.jsonc`
+- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\neocode\neocode.jsonc`
+
+If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:
+
+```jsonc
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "plugin": [],
+}
+```
+
+#### Check plugin directories
+
+NeoCode can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the desktop app:
+
+- **Global plugins**
+  - **macOS/Linux**: `~/.config/neocode/plugins/`
+  - **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\neocode\plugins`
+- **Project plugins** (only if you use per-project config)
+  - `<your-project>/.neocode/plugins/`
+
+If the app starts working again, re-enable plugins one at a time to find which one is causing the issue.
+
+---
+
+### Clear the cache
+
+If disabling plugins doesn't help (or a plugin install is stuck), clear the cache so NeoCode can rebuild it.
+
+1. Quit NeoCode Desktop completely.
+2. Delete the cache directory:
+
+- **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/neocode`
+- **Linux**: delete `~/.cache/neocode` (or run `rm -rf ~/.cache/neocode`)
+- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.cache\neocode`
+
+3. Restart NeoCode Desktop.
+
+---
+
+### Fix server connection issues
+
+NeoCode Desktop can either start its own local server (default) or connect to a server URL you configured.
+
+If you see a **"Connection Failed"** dialog (or the app never gets past the splash screen), check for a custom server URL.
+
+#### Clear the desktop default server URL
+
+From the Home screen, click the server name (with the status dot) to open the Server picker. In the **Default server** section, click **Clear**.
+
+#### Remove `server.port` / `server.hostname` from your config
+
+If your `neocode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
+
+#### Check environment variables
+
+If you have `NEOCODE_PORT` set in your environment, the desktop app will try to use that port for the local server.
+
+- Unset `NEOCODE_PORT` (or pick a free port) and restart.
+
+---
+
+### Linux: Wayland / X11 issues
+
+On Linux, some Wayland setups can cause blank windows or compositor errors.
+
+- If you're on Wayland and the app is blank/crashing, try launching with `OC_ALLOW_WAYLAND=1`.
+- If that makes things worse, remove it and try launching under an X11 session instead.
+
+---
+
+### Windows: WebView2 runtime
+
+On Windows, NeoCode Desktop requires the Microsoft Edge **WebView2 Runtime**. If the app opens to a blank window or won't start, install/update WebView2 and try again.
+
+---
+
+### Windows: General performance issues
+
+If you're experiencing slow performance, file access issues, or terminal problems on Windows, try using [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL provides a Linux environment that works more seamlessly with NeoCode's features.
+
+---
+
+### Notifications not showing
+
+NeoCode Desktop only shows system notifications when:
+
+- notifications are enabled for NeoCode in your OS settings, and
+- the app window is not focused.
+
+---
+
+### Reset desktop app storage (last resort)
+
+If the app won't start and you can't clear settings from inside the UI, reset the desktop app's saved state.
+
+1. Quit NeoCode Desktop.
+2. Find and delete these files (they live in the NeoCode Desktop app data directory):
+
+- `neocode.settings.dat` (desktop default server URL)
+- `neocode.global.dat` and `neocode.workspace.*.dat` (UI state like recent servers/projects)
+
+To find the directory quickly:
+
+- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support` (then search for the filenames above)
+- **Linux**: search under `~/.local/share` for the filenames above
+- **Windows**: Press `WIN+R` -> `%APPDATA%` (then search for the filenames above)
+
+---
+
+## Getting help
+
+If you're experiencing issues with NeoCode:
+
+1. **Report issues on GitHub**
+
+   The best way to report bugs or request features is through our GitHub repository:
+
+   [**github.com/neopilot-ai/neocode/issues**](https://github.com/neopilot-ai/neocode/issues)
+
+   Before creating a new issue, search existing issues to see if your problem has already been reported.
+
+2. **Join our Discord**
+
+   For real-time help and community discussion, join our Discord server:
+
+   [**neo.khulnasoft.com/discord**](https://neo.khulnasoft.com/discord)
+
+---
+
+## Common issues
+
+Here are some common issues and how to resolve them.
+
+---
+
+### NeoCode won't start
+
+1. Check the logs for error messages
+2. Try running with `--print-logs` to see output in the terminal
+3. Ensure you have the latest version with `neocode upgrade`
+
+---
+
+### Authentication issues
+
+1. Try re-authenticating with the `/connect` command in the TUI
+2. Check that your API keys are valid
+3. Ensure your network allows connections to the provider's API
+
+---
+
+### Model not available
+
+1. Check that you've authenticated with the provider
+2. Verify the model name in your config is correct
+3. Some models may require specific access or subscriptions
+
+If you encounter `ProviderModelNotFoundError` you are most likely incorrectly
+referencing a model somewhere.
+Models should be referenced like so: `<providerId>/<modelId>`
+
+Examples:
+
+- `openai/gpt-4.1`
+- `openrouter/google/gemini-2.5-flash`
+- `neocode/kimi-k2`
+
+To figure out what models you have access to, run `neocode models`
+
+---
+
+### ProviderInitError
+
+If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration.
+
+To resolve this:
+
+1. First, verify your provider is set up correctly by following the [providers guide](/docs/providers)
+2. If the issue persists, try clearing your stored configuration:
+
+   ```bash
+   rm -rf ~/.local/share/neocode
+   ```
+
+   On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\neocode`
+
+3. Re-authenticate with your provider using the `/connect` command in the TUI.
+
+---
+
+### AI_APICallError and provider package issues
+
+If you encounter API call errors, this may be due to outdated provider packages. neocode dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.
+
+To resolve provider package issues:
+
+1. Clear the provider package cache:
+
+   ```bash
+   rm -rf ~/.cache/neocode
+   ```
+
+   On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\neocode`
+
+2. Restart neocode to reinstall the latest provider packages
+
+This will force neocode to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.
+
+---
+
+### Copy/paste not working on Linux
+
+Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:
+
+**For X11 systems:**
+
+```bash
+apt install -y xclip
+# or
+apt install -y xsel
+```
+
+**For Wayland systems:**
+
+```bash
+apt install -y wl-clipboard
+```
+
+**For headless environments:**
+
+```bash
+apt install -y xvfb
+# and run:
+Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+export DISPLAY=:99.0
+```
+
+neocode will detect if you're using Wayland and prefer `wl-clipboard`, otherwise it will try to find clipboard tools in order of: `xclip` and `xsel`.

package/src/content/docs/tui.mdx

@@ -0,0 +1,390 @@
+---
+title: TUI
+description: Using the NeoCode terminal user interface.
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components"
+
+NeoCode provides an interactive terminal interface or TUI for working on your projects with an LLM.
+
+Running NeoCode starts the TUI for the current directory.
+
+```bash
+neocode
+```
+
+Or you can start it for a specific working directory.
+
+```bash
+neocode /path/to/project
+```
+
+Once you're in the TUI, you can prompt it with a message.
+
+```text
+Give me a quick summary of the codebase.
+```
+
+---
+
+## File references
+
+You can reference files in your messages using `@`. This does a fuzzy file search in the current working directory.
+
+:::tip
+You can also use `@` to reference files in your messages.
+:::
+
+```text "@packages/functions/src/api/index.ts"
+How is auth handled in @packages/functions/src/api/index.ts?
+```
+
+The content of the file is added to the conversation automatically.
+
+---
+
+## Bash commands
+
+Start a message with `!` to run a shell command.
+
+```bash frame="none"
+!ls -la
+```
+
+The output of the command is added to the conversation as a tool result.
+
+---
+
+## Commands
+
+When using the NeoCode TUI, you can type `/` followed by a command name to quickly execute actions. For example:
+
+```bash frame="none"
+/help
+```
+
+Most commands also have keybind using `ctrl+x` as the leader key, where `ctrl+x` is the default leader key. [Learn more](/docs/keybinds).
+
+Here are all available slash commands:
+
+---
+
+### connect
+
+Add a provider to NeoCode. Allows you to select from available providers and add their API keys.
+
+```bash frame="none"
+/connect
+```
+
+---
+
+### compact
+
+Compact the current session. _Alias_: `/summarize`
+
+```bash frame="none"
+/compact
+```
+
+**Keybind:** `ctrl+x c`
+
+---
+
+### details
+
+Toggle tool execution details.
+
+```bash frame="none"
+/details
+```
+
+**Keybind:** `ctrl+x d`
+
+---
+
+### editor
+
+Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup).
+
+```bash frame="none"
+/editor
+```
+
+**Keybind:** `ctrl+x e`
+
+---
+
+### exit
+
+Exit NeoCode. _Aliases_: `/quit`, `/q`
+
+```bash frame="none"
+/exit
+```
+
+**Keybind:** `ctrl+x q`
+
+---
+
+### export
+
+Export current conversation to Markdown and open in your default editor. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup).
+
+```bash frame="none"
+/export
+```
+
+**Keybind:** `ctrl+x x`
+
+---
+
+### help
+
+Show the help dialog.
+
+```bash frame="none"
+/help
+```
+
+**Keybind:** `ctrl+x h`
+
+---
+
+### init
+
+Create or update `AGENTS.md` file. [Learn more](/docs/rules).
+
+```bash frame="none"
+/init
+```
+
+**Keybind:** `ctrl+x i`
+
+---
+
+### models
+
+List available models.
+
+```bash frame="none"
+/models
+```
+
+**Keybind:** `ctrl+x m`
+
+---
+
+### new
+
+Start a new session. _Alias_: `/clear`
+
+```bash frame="none"
+/new
+```
+
+**Keybind:** `ctrl+x n`
+
+---
+
+### redo
+
+Redo a previously undone message. Only available after using `/undo`.
+
+:::tip
+Any file changes will also be restored.
+:::
+
+Internally, this uses Git to manage the file changes. So your project **needs to
+be a Git repository**.
+
+```bash frame="none"
+/redo
+```
+
+**Keybind:** `ctrl+x r`
+
+---
+
+### sessions
+
+List and switch between sessions. _Aliases_: `/resume`, `/continue`
+
+```bash frame="none"
+/sessions
+```
+
+**Keybind:** `ctrl+x l`
+
+---
+
+### share
+
+Share current session. [Learn more](/docs/share).
+
+```bash frame="none"
+/share
+```
+
+**Keybind:** `ctrl+x s`
+
+---
+
+### themes
+
+List available themes.
+
+```bash frame="none"
+/theme
+```
+
+**Keybind:** `ctrl+x t`
+
+---
+
+### thinking
+
+Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model's reasoning process for models that support extended thinking.
+
+:::note
+This command only controls whether thinking blocks are **displayed** - it does not enable or disable the model's reasoning capabilities. To toggle actual reasoning capabilities, use `ctrl+t` to cycle through model variants.
+:::
+
+```bash frame="none"
+/thinking
+```
+
+---
+
+### undo
+
+Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.
+
+:::tip
+Any file changes made will also be reverted.
+:::
+
+Internally, this uses Git to manage the file changes. So your project **needs to
+be a Git repository**.
+
+```bash frame="none"
+/undo
+```
+
+**Keybind:** `ctrl+x u`
+
+---
+
+### unshare
+
+Unshare current session. [Learn more](/docs/share#un-sharing).
+
+```bash frame="none"
+/unshare
+```
+
+---
+
+## Editor setup
+
+Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable.
+
+<Tabs>
+  <TabItem label="Linux/macOS">
+    ```bash
+    # Example for nano or vim
+    export EDITOR=nano
+    export EDITOR=vim
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    export EDITOR="code --wait"
+    ```
+
+    To make it permanent, add this to your shell profile;
+    `~/.bashrc`, `~/.zshrc`, etc.
+
+  </TabItem>
+
+  <TabItem label="Windows (CMD)">
+    ```bash
+    set EDITOR=notepad
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    set EDITOR=code --wait
+    ```
+
+    To make it permanent, use **System Properties** > **Environment
+    Variables**.
+
+  </TabItem>
+
+  <TabItem label="Windows (PowerShell)">
+    ```powershell
+    $env:EDITOR = "notepad"
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    $env:EDITOR = "code --wait"
+    ```
+
+    To make it permanent, add this to your PowerShell profile.
+
+  </TabItem>
+</Tabs>
+
+Popular editor options include:
+
+- `code` - Visual Studio Code
+- `cursor` - Cursor
+- `windsurf` - Windsurf
+- `nvim` - Neovim editor
+- `vim` - Vim editor
+- `nano` - Nano editor
+- `notepad` - Windows Notepad
+- `subl` - Sublime Text
+
+:::note
+Some editors like VS Code need to be started with the `--wait` flag.
+:::
+
+Some editors need command-line arguments to run in blocking mode. The `--wait` flag makes the editor process block until closed.
+
+---
+
+## Configure
+
+You can customize TUI behavior through your NeoCode config file.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "tui": {
+    "scroll_speed": 3,
+    "scroll_acceleration": {
+      "enabled": true
+    }
+  }
+}
+```
+
+### Options
+
+- `scroll_acceleration` - Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. **This setting takes precedence over `scroll_speed` and overrides it when enabled.**
+- `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (minimum: `1`). Defaults to `3`. **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.**
+
+---
+
+## Customization
+
+You can customize various aspects of the TUI view using the command palette (`ctrl+x h` or `/help`). These settings persist across restarts.
+
+---
+
+#### Username display
+
+Toggle whether your username appears in chat messages. Access this through:
+
+- Command palette: Search for "username" or "hide username"
+- The setting persists automatically and will be remembered across TUI sessions