diff --git a/docs/EDITORS/KIRO_SETUP.md b/docs/EDITORS/KIRO_SETUP.md
index 136940e71..3ee44baaa 100644
--- a/docs/EDITORS/KIRO_SETUP.md
+++ b/docs/EDITORS/KIRO_SETUP.md
@@ -1,73 +1,367 @@
 # 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's 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 90ad6193f..9d5a69b9f 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 the OpenVSX `EffortlessMetrics.perl-lsp-rs` extension in Kiro IDE; for Kiro CLI, configure a workspace custom LSP that launches `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 | connect an MCP LSP bridge to `perllsp --stdio` | [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) |
@@ -119,8 +119,41 @@ 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:
+
+```text
+EffortlessMetrics.perl-lsp-rs
+```
+
+The extension can auto-download `perllsp`. For offline or pinned deployments,
+set:
+
+```json
+{
+  "perl-lsp.serverPath": "/absolute/path/to/perllsp",
+  "perl-lsp.autoDownload": false
+}
+```
+
+For Kiro CLI, run `/code init` in the project root and edit the generated LSP
+configuration to launch:
+
+```json
+{
+  "languages": {
+    "perl": {
+      "name": "perl-lsp",
+      "command": "perllsp",
+      "args": ["--stdio"],
+      "file_extensions": ["pl", "PL", "pm", "t", "psgi"],
+      "project_patterns": [".perl-lsp.toml", "Makefile.PL", "Build.PL", "cpanfile", "dist.ini", ".git"]
+    }
+  }
+}
+```
+
+Kiro CLI Perl support is a custom-LSP path, so verify diagnostics, hover,
+definition, references, and rename in your installed Kiro CLI version.
 
 ### Claude Code
 
diff --git a/docs/how-to/TROUBLESHOOTING.md b/docs/how-to/TROUBLESHOOTING.md
index dc7edd959..ea1fa481d 100644
--- a/docs/how-to/TROUBLESHOOTING.md
+++ b/docs/how-to/TROUBLESHOOTING.md
@@ -66,6 +66,54 @@ If the editor is using a helper extension or plugin, check its own logs too.
 - Check whether the current file actually has a Perl mode or file type.
 - Inspect the LSP log for capability negotiation or request errors.
 
+### 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, use 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 that
+   launches `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.
+
 ## DAP Or Debugging Issues
 
 If you are debugging with `perl-dap`, check the DAP guide:
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 18977a4ea..3d5bc3758 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -615,7 +615,7 @@ behaviour such as binary management and feature toggles.
 
 | Setting | Type | Default | Description |
 |---|---|---|---|
-| `perl-lsp.serverPath` | `string` | `""` | Absolute path to the `perl-lsp` binary. Empty = auto-download. |
+| `perl-lsp.serverPath` | `string` | `""` | Absolute path to the `perllsp` binary. Empty = auto-download. |
 | `perl-lsp.autoDownload` | `boolean` | `true` | Download the binary automatically if not found locally. |
 | `perl-lsp.downloadBaseUrl` | `string` | `""` | Override the GitHub releases base URL for internal mirrors. |
 | `perl-lsp.channel` | `"latest"\|"stable"\|"tag"` | `"latest"` | Release channel to track. |
@@ -647,6 +647,44 @@ behaviour such as binary management and feature toggles.
 | `perl-lsp.perltidyConfig` | `string` | `""` | Path to a `.perltidyrc` configuration file. Empty = use Perl::Tidy defaults. |
 | `perl-lsp.featureProfile` | `string` | `"auto"` | Feature profile passed to the server at startup (see [Feature Profiles](#feature-profiles)). |
 
+### Amazon Kiro
+
+Kiro IDE uses VS Code-compatible extensions from OpenVSX. Prefer the
+`EffortlessMetrics.perl-lsp-rs` extension. For manual binary management:
+
+```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 config file:
+
+```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
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ---
 
 ## DAP Debug Configuration