feat(lightspeed): rename config namespace to intelligent-assistant and update rbac policy name (#3538)

* feat(lightspeed): rename config namespace to intelligent-assistant and update rbac policy name

Signed-off-by: its-mitesh-kumar <itsmiteshkumar98@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* updating change to major

Signed-off-by: its-mitesh-kumar <itsmiteshkumar98@gmail.com>

* added depreciation warning

Signed-off-by: its-mitesh-kumar <itsmiteshkumar98@gmail.com>

---------

Signed-off-by: its-mitesh-kumar <itsmiteshkumar98@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: its-mitesh-kumar

workspaces/lightspeed/.changeset/clever-foxes-dance.md

@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-lightspeed': major
+'@red-hat-developer-hub/backstage-plugin-lightspeed-backend': major
+'@red-hat-developer-hub/backstage-plugin-lightspeed-common': major
+---
+
+BREAKING CHANGE: The configuration namespace has been renamed from `lightspeed` to `intelligent-assistant`. Update your `app-config.yaml` to replace `lightspeed:` with `intelligent-assistant:`. RBAC permission policy names have also been renamed (e.g., `lightspeed.chat.read` → `intelligent-assistant.chat.read`). Update your `rbac-policy.csv` accordingly. See the migration guide in the lightspeed-backend plugin's README for full details.

workspaces/lightspeed/app-config.yaml

@@ -17,7 +17,7 @@ organization:
   name: Red Hat
 
 # Disable AI Notebooks feature by default
-lightspeed:
+intelligent-assistant:
   notebooks:
     enabled: ${NOTEBOOKS_ENABLED:-false}
     queryDefaults:

workspaces/lightspeed/packages/app/package.json

@@ -19,6 +19,7 @@
     "lint": "backstage-cli package lint"
   },
   "dependencies": {
+    "@backstage-community/plugin-rbac": "^1.51.0",
     "@backstage/cli": "^0.36.0",
     "@backstage/core-compat-api": "^0.5.6",
     "@backstage/core-components": "^0.18.8",

workspaces/lightspeed/packages/app/src/modules/nav/Sidebar.tsx

@@ -46,6 +46,7 @@ export const SidebarContent = NavContentBlueprint.make({
           </SidebarGroup>
           <SidebarSpace />
           <SidebarDivider />
+          {nav.take('page:rbac')}
           {nav.take('page:user-settings')}
         </Sidebar>
       );

workspaces/lightspeed/plugins/lightspeed-backend/README.md

@@ -25,14 +25,43 @@ backend.add(
 backend.start();
 ```
 
+### Migration from `lightspeed` to `intelligent-assistant`
+
+If you are upgrading from a previous version, the configuration namespace and RBAC permission names have changed:
+
+**Configuration** — rename the top-level key in `app-config.yaml`:
+
+| Before        | After                    |
+| ------------- | ------------------------ |
+| `lightspeed:` | `intelligent-assistant:` |
+
+All nested keys (`servicePort`, `systemPrompt`, `prompts`, `mcpServers`, `notebooks`, etc.) remain the same.
+
+**RBAC policies** — update permission names in your `rbac-policy.csv`:
+
+| Before                     | After                                 |
+| -------------------------- | ------------------------------------- |
+| `lightspeed.chat.read`     | `intelligent-assistant.chat.read`     |
+| `lightspeed.chat.create`   | `intelligent-assistant.chat.create`   |
+| `lightspeed.chat.delete`   | `intelligent-assistant.chat.delete`   |
+| `lightspeed.chat.update`   | `intelligent-assistant.chat.update`   |
+| `lightspeed.notebooks.use` | `intelligent-assistant.notebooks.use` |
+| `lightspeed.mcp.read`      | `intelligent-assistant.mcp.read`      |
+| `lightspeed.mcp.manage`    | `intelligent-assistant.mcp.manage`    |
+
+> **Warning**: The old `lightspeed:` config key and `lightspeed.*` permission names are no longer recognized. Existing deployments that do not update will silently lose functionality.
+
 ### Plugin Configurations
 
 Add the following lightspeed configurations into your `app-config.yaml` file:
 
 ```yaml
-lightspeed:
+intelligent-assistant:
   servicePort: <portNumber> # Optional - Change the LS service port number. Defaults to 8080.
   systemPrompt: <system prompt> # Optional - Override the default system prompt.
+  prompts: # Optional - Custom prompts displayed to users in the chat UI
+    - title: <prompt_title>
+      message: <prompt_message>
   mcpServers: # Optional - one or more MCP servers
     - name: <mcp server name> # must match the name configured in LCS
       token: ${MCP_TOKEN}
@@ -63,9 +92,17 @@ The Lightspeed Backend plugin has support for the permission framework.
 - When [RBAC permission](https://github.com/backstage/community-plugins/tree/main/workspaces/rbac/plugins/rbac-backend#installation) framework is enabled, for non-admin users to access lightspeed backend API, the role associated with your user should have the following permission policies associated with it. Add the following in your permission policies configuration file named `rbac-policy.csv`:
 
 ```CSV
-p, role:default/team_a, lightspeed.chat.read, read, allow
-p, role:default/team_a, lightspeed.chat.create, create, allow
-p, role:default/team_a, lightspeed.chat.delete, delete, allow
+p, role:default/team_a, intelligent-assistant.chat.read, read, allow
+p, role:default/team_a, intelligent-assistant.chat.create, create, allow
+p, role:default/team_a, intelligent-assistant.chat.delete, delete, allow
+p, role:default/team_a, intelligent-assistant.chat.update, update, allow
+
+# Required for Notebooks feature (if enabled)
+p, role:default/team_a, intelligent-assistant.notebooks.use, update, allow
+
+# Required for MCP server management (if configured)
+p, role:default/team_a, intelligent-assistant.mcp.read, read, allow
+p, role:default/team_a, intelligent-assistant.mcp.manage, update, allow
 
 g, user:default/<your-user-name>, role:default/team_a
 
@@ -101,7 +138,7 @@ For Llama Stack setup and configuration, refer to the [Llama Stack documentation
 To enable Notebooks, add the following configuration to your `app-config.yaml`:
 
 ```yaml
-lightspeed:
+intelligent-assistant:
   servicePort: 8080 # Optional: Lightspeed Core service port (default: 8080)
 
   notebooks:
@@ -125,7 +162,7 @@ lightspeed:
 
 **Core Settings**:
 
-- **`lightspeed.servicePort`** _(optional)_: Port where Lightspeed Core service is running (default: `8080`). The backend connects to Lightspeed Core at `http://{DEFAULT_LIGHTSPEED_SERVICE_HOST}:{servicePort}` to proxy vector store operations. The host is defined by the `DEFAULT_LIGHTSPEED_SERVICE_HOST` constant in the source.
+- **`intelligent-assistant.servicePort`** _(optional)_: Port where Lightspeed Core service is running (default: `8080`). The backend connects to Lightspeed Core at `http://{DEFAULT_LIGHTSPEED_SERVICE_HOST}:{servicePort}` to proxy vector store operations. The host is defined by the `DEFAULT_LIGHTSPEED_SERVICE_HOST` constant in the source.
 
 **Notebooks Settings**:
 
@@ -177,7 +214,7 @@ When enabled, Notebooks exposes the following REST API endpoints:
 **Notes**:
 
 - All endpoints require authentication (user context is automatically provided by Backstage)
-- All `/v1/*` endpoints require the `lightspeed.notebooks.use` permission
+- All `/v1/*` endpoints require the `intelligent-assistant.notebooks.use` permission
 - Document endpoints verify session ownership before allowing operations
 - `documentId` in paths is the document title (URL-encoded for special characters)
 
@@ -186,9 +223,9 @@ When enabled, Notebooks exposes the following REST API endpoints:
 When RBAC is enabled, users need the following permission to use Notebooks:
 
 ```CSV
-p, role:default/team_a, lightspeed.notebooks.use, update, allow
+p, role:default/team_a, intelligent-assistant.notebooks.use, update, allow
 
 g, user:default/<your-user-name>, role:default/team_a
 ```
 
-Add this to your `rbac-policy.csv` file along with the existing lightspeed permissions.
+Add this to your `rbac-policy.csv` file along with the existing intelligent-assistant permissions.

workspaces/lightspeed/plugins/lightspeed-backend/app-config.yaml

@@ -1,5 +1,5 @@
 # OPTIONAL: Backend-only configurations
-#lightspeed:
+#intelligent-assistant:
 #  servicePort: 8080 # OPTIONAL: Port for lightspeed-core service (default: 8080)
 #  systemPrompt: <custom_system_prompt> # OPTIONAL: Override default RHDH system prompt
 #

workspaces/lightspeed/plugins/lightspeed-backend/config.d.ts

@@ -16,10 +16,10 @@
 
 export interface Config {
   /**
-   * Configuration required for using lightspeed
+   * Configuration required for using intelligent-assistant
    * @visibility frontend
    */
-  lightspeed?: {
+  'intelligent-assistant'?: {
     /**
      * configure the port number for the lightspeed service.
      * @visibility backend

workspaces/lightspeed/plugins/lightspeed-backend/src/plugin.ts

@@ -51,21 +51,31 @@ export const lightspeedPlugin = createBackendPlugin({
       }) {
         await migrate(database);
 
+        if (config.has('lightspeed')) {
+          logger.warn(
+            'DEPRECATED: The "lightspeed" configuration key has been renamed to "intelligent-assistant". ' +
+              'Please update your app-config.yaml. The old "lightspeed" key is no longer read. ' +
+              'Migration guide: https://github.com/redhat-developer/rhdh-plugins/blob/main/workspaces/lightspeed/plugins/lightspeed-backend/README.md#migration-from-lightspeed-to-intelligent-assistant',
+          );
+        }
+
         const aiNotebooksEnabled =
-          config.getOptionalBoolean('lightspeed.notebooks.enabled') ?? false;
+          config.getOptionalBoolean(
+            'intelligent-assistant.notebooks.enabled',
+          ) ?? false;
 
         if (aiNotebooksEnabled) {
           const queryModel = config.getOptionalString(
-            'lightspeed.notebooks.queryDefaults.model',
+            'intelligent-assistant.notebooks.queryDefaults.model',
           );
           const queryProvider = config.getOptionalString(
-            'lightspeed.notebooks.queryDefaults.provider_id',
+            'intelligent-assistant.notebooks.queryDefaults.provider_id',
           );
 
           if (!queryModel || !queryProvider) {
             logger.warn(
               'AI Notebooks feature is enabled but required configuration is missing. ' +
-                'Please configure lightspeed.notebooks.queryDefaults.model and lightspeed.notebooks.queryDefaults.provider_id. ' +
+                'Please configure intelligent-assistant.notebooks.queryDefaults.model and intelligent-assistant.notebooks.queryDefaults.provider_id. ' +
                 'Notebooks will not be available until these are set.',
             );
           } else {

workspaces/lightspeed/plugins/lightspeed-backend/src/service/mcp-server.test.ts

@@ -38,7 +38,7 @@ import { lightspeedPlugin } from '../plugin';
 const mockUserId = 'user:default/user1';
 
 const BASE_CONFIG = {
-  lightspeed: {
+  'intelligent-assistant': {
     servers: [
       {
         id: 'test-server',
@@ -52,8 +52,8 @@ const BASE_CONFIG = {
 // URLs are not in app-config — they come from LCS (GET /v1/mcp-servers).
 // The LCS mock in lcsHandlers returns URLs for 'static-mcp' and 'no-token-server'.
 const MCP_CONFIG = {
-  lightspeed: {
-    ...BASE_CONFIG.lightspeed,
+  'intelligent-assistant': {
+    ...BASE_CONFIG['intelligent-assistant'],
     mcpServers: [
       {
         name: 'static-mcp',
@@ -64,8 +64,8 @@ const MCP_CONFIG = {
 };
 
 const MCP_CONFIG_MULTI = {
-  lightspeed: {
-    ...BASE_CONFIG.lightspeed,
+  'intelligent-assistant': {
+    ...BASE_CONFIG['intelligent-assistant'],
     mcpServers: [
       {
         name: 'static-mcp',
@@ -84,8 +84,8 @@ const MCP_CONFIG_ENCRYPTED = {
       keys: [{ secret: 'EXAMPLE-key-EXAMPLE-key-EXAMPLE!' }], // notsecret
     },
   },
-  lightspeed: {
-    ...BASE_CONFIG.lightspeed,
+  'intelligent-assistant': {
+    ...BASE_CONFIG['intelligent-assistant'],
     mcpServers: [
       {
         name: 'static-mcp',

workspaces/lightspeed/plugins/lightspeed-backend/src/service/notebooks/documents/documentService.test.ts

@@ -51,7 +51,7 @@ describe('DocumentService', () => {
     resetMockStorage();
     const config = mockServices.rootConfig({
       data: {
-        lightspeed: {
+        'intelligent-assistant': {
           notebooks: {
             sessionDefaults: {
               provider_id: 'test-notebooks',