docs: expand documentation of the feature

README.md

@@ -1,16 +1,24 @@
 # Sysdig LSP
 
-Sysdig LSP is a Language Server Protocol (LSP) implementation that seamlessly integrates vulnerability management into your preferred editor. It scans images defined in Dockerfiles and requires manual configuration.
-
-For Visual Studio Code users, we highly recommend the [Sysdig VSCode Extension](https://marketplace.visualstudio.com/items?itemName=sysdig.sysdig-vscode-ext). This extension delivers full LSP functionality along with additional features, ensuring an optimal experience. Although the LSP is designed to eventually replace the extension, the extension currently remains the best option for VSCode.
-
-Repository: [https://github.com/sysdiglabs/sysdig-lsp](https://github.com/sysdiglabs/sysdig-lsp)
+**Sysdig LSP** is a Language Server Protocol implementation that integrates vulnerability scanning directly into your editor.
+It enables quick scans of Dockerfiles, Docker Compose files, Kubernetes manifests, and Infrastructure-as-Code (IaC) files,
+helping you detect vulnerabilities and misconfigurations earlier in the development process.
+
+> [!NOTE]
+> For Visual Studio Code users, we highly recommend the [Sysdig VSCode Extension](https://marketplace.visualstudio.com/items?itemName=sysdig.sysdig-vscode-ext).
+>
+> This extension currently provides full LSP functionality and additional features for the best experience.
+>
+> In the future, the extension will internally leverage the Sysdig LSP implementation, ensuring consistent features and a unified experience across all editors.
+>
+> Repository: [https://github.com/sysdiglabs/sysdig-lsp](https://github.com/sysdiglabs/sysdig-lsp)
 
 ## Features
 
 | Feature                         | **[VSCode Extension](https://github.com/sysdiglabs/vscode-extension)** | **Sysdig LSP**                                           |
 |---------------------------------|------------------------------------------------------------------------|----------------------------------------------------------|
 | Scan base image in Dockerfile   | Supported                                                              | [Supported](./docs/features/scan_base_image.md) (0.1.0+) |
+| Code lens support               | Supported                                                              | In roadmap                                               |
 | Build and Scan Dockerfile       | Supported                                                              | In roadmap                                               |
 | Layered image analysis          | Supported                                                              | In roadmap                                               |
 | Docker-compose image analysis   | Supported                                                              | In roadmap                                               |

docs/features/scan_base_image.md

@@ -1,3 +1,35 @@
 # Scan Base Image
 
-![](./scan_base_image.gif)
+Sysdig LSP scans the base image defined in your Dockerfile to identify vulnerabilities early in your development workflow.
+
+> [!IMPORTANT]
+> Sysdig LSP analyzes only the final FROM instruction(s), as this specifies the runtime base image for your container.
+>
+> Intermediate stages defined in multi-stage Dockerfiles (e.g., builder images) are intentionally ignored because they don't
+> form part of the final runtime environment.
+
+![Sysdig LSP executing base image scan in the Helix editor](./scan_base_image.gif)
+
+## Examples
+
+### Single-stage Dockerfile (scanned)
+
+```dockerfile
+# Base image used for this Dockerfile
+FROM alpine:latest
+```
+
+### Multi-stage Dockerfile (only the final stage is scanned)
+
+```dockerfile
+# Build stage (ignored by Sysdig LSP)
+FROM golang:1.19 AS build
+RUN go build -o app main.go
+
+# Final image (scanned by Sysdig LSP)
+FROM alpine:3.17
+COPY --from=build /app /app
+ENTRYPOINT ["/app"]
+```
+
+In this multi-stage Dockerfile, Sysdig LSP scans only the final stage (`alpine:3.17`).