diff --git a/crates/perl-lsp-rs/src/runtime/file_watcher_debounce.rs b/crates/perl-lsp-rs/src/runtime/file_watcher_debounce.rs
index d411693495..04d90b3a11 100644
--- a/crates/perl-lsp-rs/src/runtime/file_watcher_debounce.rs
+++ b/crates/perl-lsp-rs/src/runtime/file_watcher_debounce.rs
@@ -260,10 +260,10 @@ mod tests {
 
         let calls = call_count.load(Ordering::SeqCst);
         let uris = total_uris.load(Ordering::SeqCst);
-        // Should coalesce into <=4 batch calls — under CI scheduler load the 100ms
+        // Should coalesce into <=6 batch calls — under CI scheduler load the 100ms
         // window may fire before all 50 events arrive, splitting into a few batches.
         // The meaningful check is that coalescence occurred (not 50 individual calls).
-        assert!(calls <= 4, "Expected <=4 batch calls for 50 rapid changes, got {calls}");
+        assert!(calls <= 6, "Expected <=6 batch calls for 50 rapid changes, got {calls}");
         assert_eq!(uris, 50, "All 50 URIs should be delivered, got {uris}");
     }
 }
diff --git a/docs/EDITORS/KIRO_SETUP.md b/docs/EDITORS/KIRO_SETUP.md
index 136940e712..580aa574e6 100644
--- a/docs/EDITORS/KIRO_SETUP.md
+++ b/docs/EDITORS/KIRO_SETUP.md
@@ -1,73 +1,362 @@
 # Amazon Kiro Setup Guide for perl-lsp
 
-This guide gives you a reliable setup path for using `perllsp` in Amazon Kiro.
+This guide covers using `perl-lsp` with Amazon Kiro.
+
+Kiro has two relevant setup paths:
+
+- **Kiro IDE** — use the VS Code-compatible `EffortlessMetrics.perl-lsp-rs` extension from OpenVSX.
+- **Kiro CLI** — use Kiro CLI workspace-scoped custom LSP configuration to launch `perllsp --stdio`.
 
 ## Prerequisites
 
-- Amazon Kiro installed
-- `perllsp` installed and available on `PATH`
-- A Perl workspace opened in Kiro
+### Kiro IDE
+
+- Kiro IDE installed
+- A Perl project opened in Kiro
+- The `EffortlessMetrics.perl-lsp-rs` extension installed from OpenVSX
+
+The extension can auto-download the matching `perllsp` binary. Install `perllsp`
+manually only for offline environments, pinned internal deployments, or when
+`perl-lsp.autoDownload` is disabled.
 
-Verify the server first:
+### Kiro CLI
+
+- Kiro CLI installed
+- `perllsp` installed and available to the shell that launches Kiro CLI
+- A Perl project opened from the project root
+
+Verify a manual `perllsp` installation:
 
 ```bash
 perllsp --version
 perllsp --health
+perllsp --info
+```
+
+## Kiro IDE Setup
+
+Kiro is built on Code OSS and uses OpenVSX-compatible extensions. Install:
+
+```text
+EffortlessMetrics.perl-lsp-rs
+```
+
+From Kiro:
+
+1. Open the Extensions panel.
+2. Search for `perl-lsp` or `EffortlessMetrics.perl-lsp-rs`.
+3. Install the extension.
+4. Open a Perl file such as `lib/My/Module.pm`, `script/app.pl`, or `t/basic.t`.
+
+The extension should activate automatically for Perl files.
+
+## Optional: Manual Binary Path for Kiro IDE
+
+Use this only when extension-managed binary download is blocked or your team
+pins a specific `perllsp` binary.
+
+```json
+{
+  "perl-lsp.serverPath": "/absolute/path/to/perllsp",
+  "perl-lsp.autoDownload": false
+}
+```
+
+On macOS/Linux:
+
+```bash
+command -v perllsp
+```
+
+On Windows PowerShell:
+
+```powershell
+where perllsp
+```
+
+## Recommended Kiro IDE Settings
+
+For most users:
+
+```json
+{
+  "perl-lsp.autoDownload": true,
+  "perl-lsp.trace.server": "off",
+  "perl-lsp.enableDiagnostics": true,
+  "perl-lsp.enableSemanticTokens": true,
+  "perl-lsp.enableFormatting": true,
+  "perl-lsp.formatOnSave": false,
+  "perl-lsp.includePaths": ["lib", ".", "local/lib/perl5"]
+}
+```
+
+Use protocol tracing only while debugging:
+
+```json
+{
+  "perl-lsp.trace.server": "messages"
+}
+```
+
+Prefer `.perl-lsp.toml` for settings shared by the whole team:
+
+```toml
+[perl]
+include_paths = ["lib", "local/lib/perl5", "vendor/lib"]
+
+[features]
+inlay_hints = true
 ```
 
-## Kiro IDE (Desktop)
+## Kiro CLI Setup
 
-Kiro IDE is built on VS Code's open-source foundation and uses the OpenVSX
-extension registry. Install the Perl LSP extension from the Extensions panel:
+Kiro CLI has optional workspace-scoped LSP integration. Run this in the project
+root:
 
-- Search for `perl-lsp` in Kiro's Extensions panel
-- Extension ID: `EffortlessMetrics.perl-lsp-rs`
+```text
+/code init
+```
 
-If the extension is not available in OpenVSX, download the `.vsix` from
-[GitHub Releases](https://github.com/EffortlessMetrics/perl-lsp/releases) and
-install it via "Install from VSIX..." in the Extensions panel menu.
+Then edit the LSP configuration file that Kiro creates.
 
-## Kiro CLI
+Current Kiro docs describe this file as project-root `lsp.json`. Some Kiro CLI
+examples and builds refer to `.kiro/settings/lsp.json`. Use the path created by
+your installed Kiro CLI.
 
-If you use the Kiro command-line interface, add a custom language server entry
-in `.kiro/settings/lsp.json` at your project root:
+Add or merge this configuration:
 
 ```json
 {
   "languages": {
     "perl": {
-      "name": "perllsp",
+      "name": "perl-lsp",
       "command": "perllsp",
       "args": ["--stdio"],
-      "file_extensions": ["pl", "pm", "t", "psgi"],
-      "project_patterns": [".perl-lsp.toml", "Makefile.PL", "Build.PL"],
-      "multi_workspace": false
+      "file_extensions": [
+        "pl",
+        "PL",
+        "pm",
+        "t",
+        "psgi",
+        "cgi",
+        "fcgi",
+        "xs",
+        "xsi"
+      ],
+      "project_patterns": [
+        ".perl-lsp.toml",
+        "Makefile.PL",
+        "Build.PL",
+        "cpanfile",
+        "dist.ini",
+        ".git"
+      ],
+      "exclude_patterns": [
+        "**/.git/**",
+        "**/local/**",
+        "**/blib/**",
+        "**/node_modules/**"
+      ],
+      "multi_workspace": false,
+      "request_timeout_secs": 60,
+      "initialization_options": {
+        "perl": {
+          "workspace": {
+            "includePaths": ["lib", ".", "local/lib/perl5"],
+            "useSystemInc": false,
+            "resolutionTimeout": 50
+          },
+          "inlayHints": {
+            "enabled": true,
+            "parameterHints": true,
+            "typeHints": true
+          },
+          "limits": {
+            "workspaceSymbolCap": 200,
+            "referencesCap": 500,
+            "completionCap": 100
+          }
+        }
+      }
     }
   }
 }
 ```
 
-Run `/code init` in the project root first if the `.kiro/settings/` directory
-does not exist, then restart the Kiro CLI to load the new configuration.
+Restart LSP servers after editing:
 
-## Recommended Workspace Settings
+```text
+/code init -f
+```
 
-- Keep your project root open as the workspace root.
-- Add include/library paths in project settings when your code uses nonstandard
-  module locations.
-- Restart the language server after changing server path or arguments.
+Check status:
+
+```text
+/code status
+```
+
+View logs:
+
+```text
+/code logs
+/code logs -l DEBUG -n 100
+```
+
+## Kiro CLI Caveat: Perl Is a Custom Language
+
+Kiro CLI's built-in tree-sitter language list does not currently include Perl.
+The custom LSP config above should still be useful for LSP-backed diagnostics
+and semantic operations, but verify behavior in your installed Kiro CLI
+version.
+
+If diagnostics work but hover, references, go-to-definition, completion, or
+rename do not, this may be a Kiro CLI custom-LSP limitation rather than a
+`perllsp` problem.
+
+## Verify It Is Running
+
+### Kiro IDE
+
+1. Open the project root in Kiro.
+2. Open a Perl file such as `.pl`, `.pm`, or `.t`.
+3. Confirm the active document language is Perl.
+4. Introduce a temporary syntax error.
+5. Confirm diagnostics appear.
+6. Remove the syntax error after testing.
+
+Try standard editor actions:
+
+- Go to Definition
+- Find References
+- Hover
+- Rename Symbol
+- Format Document
+
+### Kiro CLI
+
+Ask Kiro CLI for LSP-backed information after `/code init`:
+
+```text
+Get diagnostics for lib/My/Module.pm
+Find references of My::Module::some_function
+What symbols are in lib/My/Module.pm?
+What's the hover documentation for My::Module::some_function?
+```
+
+Also check the server outside Kiro:
+
+```bash
+perllsp --check path/to/file.pl
+```
 
 ## Troubleshooting
 
-1. **Server does not start**
-   - Run `perllsp --health` in an external shell.
-   - Confirm Kiro inherits the same `PATH` as your shell.
-2. **No diagnostics or completions**
-   - Confirm the file is recognized as Perl.
-   - Confirm the LSP client is attached to the current buffer/file.
-3. **Definitions/references incomplete**
-   - Open the repository root, not a nested subfolder.
-   - Ensure local library paths are configured in project settings.
-
-For cross-editor fallback patterns, see [Editor Setup](../how-to/EDITOR_SETUP.md)
-and [Troubleshooting](../how-to/TROUBLESHOOTING.md).
+### Kiro IDE extension does not install
+
+- Confirm the extension is available from OpenVSX.
+- Update Kiro to a current build.
+- If your organization uses a custom extension registry, confirm it mirrors `EffortlessMetrics.perl-lsp-rs`.
+- If extension download is blocked by firewall or proxy policy, allow OpenVSX extension metadata and VSIX download hosts or install from an approved internal registry.
+
+### Kiro IDE cannot find `perllsp`
+
+If using extension auto-download, confirm:
+
+```json
+{
+  "perl-lsp.autoDownload": true
+}
+```
+
+If using a manual binary:
+
+```bash
+perllsp --version
+perllsp --health
+perllsp --info
+```
+
+If Kiro was launched from a GUI, it may not inherit your shell `PATH`. Use an
+absolute `perl-lsp.serverPath` when needed.
+
+### Kiro CLI cannot start `perllsp`
+
+Check the binary from the same shell used to launch Kiro CLI:
+
+```bash
+command -v perllsp
+perllsp --version
+perllsp --health
+perllsp --info
+```
+
+On Windows PowerShell:
+
+```powershell
+where perllsp
+perllsp --version
+perllsp --health
+perllsp --info
+```
+
+Then restart LSP servers:
+
+```text
+/code init -f
+```
+
+Check logs:
+
+```text
+/code logs -l ERROR
+/code logs -l DEBUG -n 100
+```
+
+### No diagnostics or completion
+
+- Confirm the file extension is listed in the Kiro CLI `file_extensions` array.
+- Confirm the active document language is Perl in Kiro IDE.
+- Confirm the workspace root is the project root, not a nested subdirectory.
+- Check `perllsp` directly:
+
+  ```bash
+  perllsp --check path/to/file.pl
+  ```
+
+### Module resolution issues
+
+Prefer `.perl-lsp.toml` for shared include paths:
+
+```toml
+[perl]
+include_paths = ["lib", "local/lib/perl5", "vendor/lib"]
+```
+
+Or use editor / CLI initialization options:
+
+```json
+{
+  "perl": {
+    "workspace": {
+      "includePaths": ["lib", ".", "local/lib/perl5", "vendor/lib"]
+    }
+  }
+}
+```
+
+### `perllsp --stdio` appears to hang
+
+That is expected. In stdio mode, `perllsp` waits for framed LSP JSON-RPC input
+from the editor or CLI. Use these commands for manual checks instead:
+
+```bash
+perllsp --health
+perllsp --info
+perllsp --check path/to/file.pl
+```
+
+## See Also
+
+- [Editor Setup](../how-to/EDITOR_SETUP.md)
+- [Configuration](../reference/CONFIG.md)
+- [Troubleshooting](../how-to/TROUBLESHOOTING.md)
diff --git a/docs/how-to/EDITOR_SETUP.md b/docs/how-to/EDITOR_SETUP.md
index 08b4362419..b41427c658 100644
--- a/docs/how-to/EDITOR_SETUP.md
+++ b/docs/how-to/EDITOR_SETUP.md
@@ -31,7 +31,7 @@ perllsp --health
 | Helix | add a `perllsp` language server entry | [docs/EDITORS/HELIX_SETUP.md](../EDITORS/HELIX_SETUP.md) |
 | Zed | install a Perl extension, then optionally point at `perllsp` | [docs/EDITORS/ZED_SETUP.md](../EDITORS/ZED_SETUP.md) |
 | Sublime Text | register `perllsp` in the LSP package settings | [docs/EDITORS/SUBLIME_SETUP.md](../EDITORS/SUBLIME_SETUP.md) |
-| Amazon Kiro | register a Perl LSP client using `perllsp --stdio` | [docs/EDITORS/KIRO_SETUP.md](../EDITORS/KIRO_SETUP.md) |
+| Amazon Kiro | use OpenVSX `EffortlessMetrics.perl-lsp-rs` in Kiro IDE; for Kiro CLI configure custom LSP `perllsp --stdio` | [docs/EDITORS/KIRO_SETUP.md](../EDITORS/KIRO_SETUP.md) |
 | Claude Code | provide a plugin `.lsp.json` pointing to `perllsp --stdio` | [docs/EDITORS/CLAUDE_CODE_SETUP.md](../EDITORS/CLAUDE_CODE_SETUP.md) |
 | Codex CLI | configure an MCP bridge such as `lsp-mcp`; the bridge exposes tools to Codex and launches `perllsp --stdio` internally | [docs/EDITORS/CODEX_CLI_SETUP.md](../EDITORS/CODEX_CLI_SETUP.md) |
 | Codex Desktop | add a custom Perl server command `perllsp --stdio` | [docs/EDITORS/CODEX_DESKTOP_SETUP.md](../EDITORS/CODEX_DESKTOP_SETUP.md) |
@@ -131,8 +131,11 @@ Register a client with `command: ["perllsp", "--stdio"]`, use a selector such as
 
 ### Amazon Kiro
 
-Register a Perl language-server client that launches `perllsp --stdio`, then
-restart the client after changing workspace settings or include paths.
+For Kiro IDE, install the OpenVSX extension `EffortlessMetrics.perl-lsp-rs`.
+The extension can auto-download `perllsp`. For Kiro CLI, run `/code init` in
+the project root and edit the generated LSP configuration so Perl launches with
+`perllsp --stdio`. Verify diagnostics, hover, definition, references, and rename
+in your installed Kiro CLI build because Perl uses the custom-LSP path there.
 
 ### Claude Code
 
diff --git a/docs/how-to/TROUBLESHOOTING.md b/docs/how-to/TROUBLESHOOTING.md
index c2ea784e8e..e4fd424408 100644
--- a/docs/how-to/TROUBLESHOOTING.md
+++ b/docs/how-to/TROUBLESHOOTING.md
@@ -105,6 +105,50 @@ If the editor is using a helper extension or plugin, check its own logs too.
 If you are debugging with `perl-dap`, check the DAP guide:
 [DAP_USER_GUIDE.md](../tutorials/DAP_USER_GUIDE.md).
 
+## Amazon Kiro Does Not Start `perllsp`
+
+### Kiro IDE
+
+1. Confirm the `EffortlessMetrics.perl-lsp-rs` extension is installed and enabled.
+2. Confirm the active file language is Perl.
+3. If using extension-managed downloads, confirm:
+
+   ```json
+   {
+     "perl-lsp.autoDownload": true
+   }
+   ```
+
+4. If using a manual binary, run:
+
+   ```bash
+   perllsp --version
+   perllsp --health
+   perllsp --info
+   ```
+
+5. If Kiro cannot find the binary, set an absolute `perl-lsp.serverPath`.
+
+### Kiro CLI
+
+1. Run `/code init` in the project root.
+2. Edit the generated LSP configuration and add a Perl server entry launching `perllsp --stdio`.
+3. Restart LSP servers:
+
+   ```text
+   /code init -f
+   ```
+
+4. Check status and logs:
+
+   ```text
+   /code status
+   /code logs -l ERROR
+   /code logs -l DEBUG -n 100
+   ```
+
+5. If diagnostics work but hover, definition, references, completion, or rename do not, verify whether your Kiro CLI build supports client-initiated operations for custom non-built-in languages.
+
 ## When To Escalate
 
 Report an issue when you can include:
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 110e26bca2..f2d38dbf85 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -1016,6 +1016,45 @@ array launches the server, `extensions` controls activation, and
 
 For settings shared across editors, prefer `.perl-lsp.toml`.
 
+#### Amazon Kiro
+
+Kiro IDE uses OpenVSX-compatible extensions. Prefer
+`EffortlessMetrics.perl-lsp-rs` and keep auto-download enabled unless you need
+pinned/offline binaries:
+
+```json
+{
+  "perl-lsp.serverPath": "/absolute/path/to/perllsp",
+  "perl-lsp.autoDownload": false
+}
+```
+
+Kiro CLI uses workspace-scoped LSP configuration. Run `/code init`, then edit
+the generated `lsp.json` (path varies by Kiro CLI build) and add a Perl entry:
+
+```json
+{
+  "languages": {
+    "perl": {
+      "name": "perl-lsp",
+      "command": "perllsp",
+      "args": ["--stdio"],
+      "file_extensions": ["pl", "PL", "pm", "t", "psgi", "cgi", "fcgi", "xs", "xsi"],
+      "project_patterns": [".perl-lsp.toml", "Makefile.PL", "Build.PL", "cpanfile", "dist.ini", ".git"],
+      "multi_workspace": false,
+      "initialization_options": {
+        "perl": {
+          "workspace": {
+            "includePaths": ["lib", ".", "local/lib/perl5"],
+            "useSystemInc": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 #### Claude Code (plugin `.lsp.json`)
 
 ```json