📝 docs: update agent instructions for new CLI capabilities

src/apx/templates/addons/claude/.mcp.json

@@ -1,16 +1,12 @@
 {
   "mcpServers": {
-    "shadcn": {
-      "command": "bun",
-      "args": ["x", "--bun", "shadcn@latest", "mcp"]
-    },
     "apx": {
       "command": "uv",
-      "args": ["run", "apx", "dev", "mcp"]
+      "args": ["run", "apx", "mcp"]
     },
     "playwright": {
-      "command": "bun",
-      "args": ["x", "--bun", "@playwright/mcp@latest"]
+      "command": "uv",
+      "args": ["run", "apx", "bun", "x", "--bun", "@playwright/mcp@latest"]
     }
   }
 }

src/apx/templates/addons/claude/CLAUDE.md.jinja2

@@ -1,18 +1,19 @@
 # Do's and Don'ts
-- If the apx development servers are started, don't regenerate the OpenAPI client.
-- Prefer running apx related commands via mcp server if it's available.
-- Prefer to add new components via shadcn mcp server if it's available.
+- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate.
+- Prefer running apx related commands via MCP server if it's available.
+- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components.
 - When using the API calls on the frontend, use error boundaries to handle errors.
-- Run apx dev check command (via CLI) to check for errors in the project code after making changes.
-- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.).
-- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures.
+- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes.
+- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.).
+- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures.
 
 ## Package Management
-- **Frontend:** Always use `bun` (never `npm`)
+- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add <dependency>`), unless user explicitly stated otherwise.
 - **Python:** Always use `uv` (never `pip`)
 
 ## Component Management
-- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation
+- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components
+- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add <component> --yes` to add components
 - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder
 - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`)
 
@@ -42,12 +43,16 @@ uv run apx dev start
 uv run apx dev status
 ```
 
-**View logs** (stored in `~/.apx/{app_id}/logs/`):
+**Check for errors** (TypeScript, Python linting):
 ```bash
-uv run apx dev logs              # All logs
-uv run apx dev logs --ui         # Frontend only
-uv run apx dev logs --backend    # Backend only
-uv run apx dev tail              # Live stream
+uv run apx dev check
+```
+
+**View logs:**
+```bash
+uv run apx dev logs              # Recent logs (default: last 10m)
+uv run apx dev logs -d 1h        # Logs from last hour
+uv run apx dev logs -f           # Follow/stream logs live
 ```
 
 **Stop servers:**
@@ -60,10 +65,22 @@ uv run apx dev stop
 uv run apx build
 ```
 
-**OpenAPI generation** (auto-runs with `dev start`):
-```bash
-uv run apx openapi               # Generate once
-uv run apx openapi --watch       # Watch mode
-```
+**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed.
+
+## MCP Tools Reference
+
+When the apx MCP server is available, use these tools:
 
-**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed.
+| Tool | Description |
+|------|-------------|
+| `start` | Start development server and return the URL |
+| `stop` | Stop the development server |
+| `restart` | Restart the development server (preserves port if possible) |
+| `logs` | Fetch recent dev server logs |
+| `check` | Check project code for errors (runs tsc and ty checks in parallel) |
+| `refresh_openapi` | Regenerate OpenAPI schema and API client |
+| `search_registry_components` | Search shadcn registry components using semantic search |
+| `add_component` | Add a component to the project |
+| `docs` | Search Databricks SDK documentation for code examples and API references |
+| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI |
+| `get_route_info` | Get code example for using a specific API route |

src/apx/templates/addons/codex/AGENTS.md.jinja2

@@ -1,18 +1,19 @@
 # Do's and Don'ts
-- If the apx development servers are started, don't regenerate the OpenAPI client.
-- Prefer running apx related commands via mcp server if it's available.
-- Prefer to add new components via shadcn mcp server if it's available.
+- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate.
+- Prefer running apx related commands via MCP server if it's available.
+- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components.
 - When using the API calls on the frontend, use error boundaries to handle errors.
-- Run apx dev check command (via CLI) to check for errors in the project code after making changes.
-- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.).
-- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures.
+- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes.
+- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.).
+- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures.
 
 ## Package Management
-- **Frontend:** Always use `bun` (never `npm`)
+- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add <dependency>`), unless user explicitly stated otherwise.
 - **Python:** Always use `uv` (never `pip`)
 
 ## Component Management
-- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation
+- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components
+- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add <component> --yes` to add components
 - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder
 - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`)
 
@@ -42,12 +43,16 @@ uv run apx dev start
 uv run apx dev status
 ```
 
-**View logs** (stored in `~/.apx/{app_id}/logs/`):
+**Check for errors** (TypeScript, Python linting):
 ```bash
-uv run apx dev logs              # All logs
-uv run apx dev logs --ui         # Frontend only
-uv run apx dev logs --backend    # Backend only
-uv run apx dev tail              # Live stream
+uv run apx dev check
+```
+
+**View logs:**
+```bash
+uv run apx dev logs              # Recent logs (default: last 10m)
+uv run apx dev logs -d 1h        # Logs from last hour
+uv run apx dev logs -f           # Follow/stream logs live
 ```
 
 **Stop servers:**
@@ -60,10 +65,22 @@ uv run apx dev stop
 uv run apx build
 ```
 
-**OpenAPI generation** (auto-runs with `dev start`):
-```bash
-uv run apx openapi               # Generate once
-uv run apx openapi --watch       # Watch mode
-```
+**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed.
+
+## MCP Tools Reference
+
+When the apx MCP server is available, use these tools:
 
-**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed.
+| Tool | Description |
+|------|-------------|
+| `start` | Start development server and return the URL |
+| `stop` | Stop the development server |
+| `restart` | Restart the development server (preserves port if possible) |
+| `logs` | Fetch recent dev server logs |
+| `check` | Check project code for errors (runs tsc and ty checks in parallel) |
+| `refresh_openapi` | Regenerate OpenAPI schema and API client |
+| `search_registry_components` | Search shadcn registry components using semantic search |
+| `add_component` | Add a component to the project |
+| `docs` | Search Databricks SDK documentation for code examples and API references |
+| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI |
+| `get_route_info` | Get code example for using a specific API route |

src/apx/templates/addons/cursor/.cursor/mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
-    "shadcn": {
-      "command": "bun",
-      "args": ["x", "--bun", "shadcn@latest", "mcp"]
-    },
     "apx": {
       "command": "uv",
-      "args": ["run", "apx", "dev", "mcp"]
+      "args": ["run", "apx", "mcp"]
     }
   }
 }

src/apx/templates/addons/cursor/.cursor/rules/project.mdc.jinja2

@@ -5,21 +5,22 @@ alwaysApply: true
 # Cursor Agent Rules
 
 # Do's and Don'ts
-- If the apx development servers are started and running, don't regenerate the OpenAPI client.
-- Prefer running apx related commands via mcp server if it's available.
-- Prefer to add new components via shadcn mcp server if it's available.
+- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate.
+- Prefer running apx related commands via MCP server if it's available.
+- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components.
 - When using the API calls on the frontend, use error boundaries to handle errors.
-- Run apx dev check command (via CLI or via mcp) to check for errors in the project code after making changes.
-- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.).
+- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes.
+- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.).
 - Avoid unnecessary restarts of the development servers
-- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures.
+- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures.
 
 ## Package Management
-- **Frontend:** Always use `bun` (never `npm`)
+- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add <dependency>`), unless user explicitly stated otherwise.
 - **Python:** Always use `uv` (never `pip`)
 
 ## Component Management
-- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation
+- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components
+- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add <component> --yes` to add components
 - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder
 - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`)
 
@@ -50,12 +51,16 @@ uv run apx dev start
 uv run apx dev status
 ```
 
-**View logs** (stored in `~/.apx/{app_id}/logs/`):
+**Check for errors** (TypeScript, Python linting):
 ```bash
-uv run apx dev logs              # All logs
-uv run apx dev logs --ui         # Frontend only
-uv run apx dev logs --backend    # Backend only
-uv run apx dev tail              # Live stream
+uv run apx dev check
+```
+
+**View logs:**
+```bash
+uv run apx dev logs              # Recent logs (default: last 10m)
+uv run apx dev logs -d 1h        # Logs from last hour
+uv run apx dev logs -f           # Follow/stream logs live
 ```
 
 **Stop servers:**
@@ -68,10 +73,22 @@ uv run apx dev stop
 uv run apx build
 ```
 
-**OpenAPI generation** (auto-runs on each change with `dev start`):
-```bash
-uv run apx openapi               # Generate once
-uv run apx openapi --watch       # Watch mode
-```
-
-**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed.
+**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed.
+
+## MCP Tools Reference
+
+When the apx MCP server is available, use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `start` | Start development server and return the URL |
+| `stop` | Stop the development server |
+| `restart` | Restart the development server (preserves port if possible) |
+| `logs` | Fetch recent dev server logs |
+| `check` | Check project code for errors (runs tsc and ty checks in parallel) |
+| `refresh_openapi` | Regenerate OpenAPI schema and API client |
+| `search_registry_components` | Search shadcn registry components using semantic search |
+| `add_component` | Add a component to the project |
+| `docs` | Search Databricks SDK documentation for code examples and API references |
+| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI |
+| `get_route_info` | Get code example for using a specific API route |

src/apx/templates/addons/vscode/.github/instructions/project.md.jinja2

@@ -5,20 +5,21 @@ alwaysApply: true
 # Copilot Rules
 
 # Do's and Don'ts
-- If the apx development servers are started, don't regenerate the OpenAPI client.
-- Prefer running apx related commands via mcp server if it's available.
-- Prefer to add new components via shadcn mcp server if it's available.
+- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate.
+- Prefer running apx related commands via MCP server if it's available.
+- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components.
 - When using the API calls on the frontend, use error boundaries to handle errors.
-- Run apx dev check command (via CLI) to check for errors in the project code after making changes.
-- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.).
-- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures.
+- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes.
+- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.).
+- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures.
 
 ## Package Management
-- **Frontend:** Always use `bun` (never `npm`)
+- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add <dependency>`), unless user explicitly stated otherwise.
 - **Python:** Always use `uv` (never `pip`)
 
 ## Component Management
-- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation
+- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components
+- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add <component> --yes` to add components
 - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder
 - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`)
 
@@ -48,12 +49,16 @@ uv run apx dev start
 uv run apx dev status
 ```
 
-**View logs** (stored in `~/.apx/{app_id}/logs/`):
+**Check for errors** (TypeScript, Python linting):
 ```bash
-uv run apx dev logs              # All logs
-uv run apx dev logs --ui         # Frontend only
-uv run apx dev logs --backend    # Backend only
-uv run apx dev tail              # Live stream
+uv run apx dev check
+```
+
+**View logs:**
+```bash
+uv run apx dev logs              # Recent logs (default: last 10m)
+uv run apx dev logs -d 1h        # Logs from last hour
+uv run apx dev logs -f           # Follow/stream logs live
 ```
 
 **Stop servers:**
@@ -66,10 +71,22 @@ uv run apx dev stop
 uv run apx build
 ```
 
-**OpenAPI generation** (auto-runs with `dev start`):
-```bash
-uv run apx openapi               # Generate once
-uv run apx openapi --watch       # Watch mode
-```
+**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed.
+
+## MCP Tools Reference
+
+When the apx MCP server is available, use these tools:
 
-**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed.
+| Tool | Description |
+|------|-------------|
+| `start` | Start development server and return the URL |
+| `stop` | Stop the development server |
+| `restart` | Restart the development server (preserves port if possible) |
+| `logs` | Fetch recent dev server logs |
+| `check` | Check project code for errors (runs tsc and ty checks in parallel) |
+| `refresh_openapi` | Regenerate OpenAPI schema and API client |
+| `search_registry_components` | Search shadcn registry components using semantic search |
+| `add_component` | Add a component to the project |
+| `docs` | Search Databricks SDK documentation for code examples and API references |
+| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI |
+| `get_route_info` | Get code example for using a specific API route |

src/apx/templates/addons/vscode/.vscode/mcp.json

@@ -1,16 +1,12 @@
 {
   "mcpServers": {
-    "shadcn": {
-      "command": "bun",
-      "args": ["x", "--bun", "shadcn@latest", "mcp"]
-    },
     "apx": {
       "command": "uv",
-      "args": ["run", "apx", "dev", "mcp"]
+      "args": ["run", "apx", "mcp"]
     },
     "playwright": {
-      "command": "bun",
-      "args": ["x", "--bun", "@playwright/mcp@latest"]
+      "command": "uv",
+      "args": ["run", "apx", "bun", "x", "--bun", "@playwright/mcp@latest"]
     }
   }
 }