docs(apps): clarify ping URL only accepts http/https

Remove URL validation from app href field to support custom URI
schemes like vscode://, microsoft-edge:https://, and myapp://open.
Only javascript: URIs remain blocked for security.

Closes #6520

apps/docs/docs/management/apps/index.mdx

@@ -7,8 +7,8 @@ tags:
   - Ping
 ---
 
-Apps are the building blocks of your Homarr board. 
-Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up. 
+Apps are the building blocks of your Homarr board.
+Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up.
 Apps are used in the bookmark and app widget.
 
 ## Create an app
@@ -27,7 +27,7 @@ The name must be at least one character long and can be chosen freely.
 
 ### Icon URL
 
-This is the URL to the icon that will be displayed on the app widget. 
+This is the URL to the icon that will be displayed on the app widget.
 You can paste a direct HTTP(S) URL to an image, search the included icon repositories by name, or upload a local file through the upload button. Direct image URLs are used as entered and are not searched in the icon repositories.
 
 ![Icon URL](./img/app-icon-url.png)
@@ -40,11 +40,14 @@ An optional description that can be shown as tooltip on the app widget.
 
 The URL to the website you want to link to. Clicking on the app widget or bookmark will open this URL.
 
+You can also use custom URI schemes such as `vscode://file/path`, `microsoft-edge:https://example.com`, or `myapp://open` to link to local applications or third-party programs. We trust that you know what you are doing — only `javascript:` URIs are blocked for security reasons.
+
 ### Ping URL
 
-When you want to use another url for the simple status check you can set it here. 
+When you want to use another url for the simple status check you can set it here.
 This will allow you to set a different URL for the ping than the URL that is opened when clicking on the app widget.
 It's useful when you want to ping the service internally for example with a custom ip but open the website externally.
+Note that the ping URL only accepts `http://` and `https://` URLs — custom URI schemes are not supported for pings.
 
 ## List of apps
 

packages/api/src/router/app.ts

@@ -173,7 +173,7 @@ export const appRouter = createTRPCRouter({
       mcp: {
         enabled: true,
         description:
-          "Create a new app (bookmark/shortcut to a service). REQUIRED: name (string), iconUrl (icon URL string), href (app URL, http/https or blank). OPTIONAL: description (string or null), pingUrl (URL to check reachability, or empty string)",
+          "Create a new app (bookmark/shortcut to a service). REQUIRED: name (string), iconUrl (icon URL string), href (app URL or custom URI scheme such as vscode://, or blank). OPTIONAL: description (string or null), pingUrl (URL to check reachability, or empty string)",
       },
     })
     .mutation(async ({ ctx, input }) => {

packages/definitions/src/docs/homarr-docs-sitemap.ts

@@ -119,6 +119,7 @@ export type HomarrDocumentationPath =
   | "/docs/tags/variables"
   | "/docs/tags/widgets"
   | "/docs/advanced/command-line"
+  | "/docs/advanced/command-line/development"
   | "/docs/advanced/command-line/fix-usernames"
   | "/docs/advanced/command-line/integrations"
   | "/docs/advanced/command-line/password-recovery"

packages/validation/src/app.ts

@@ -3,8 +3,7 @@ import { z } from "zod/v4";
 export const appHrefSchema = z
   .string()
   .trim()
-  .url()
-  .regex(/^(?!javascript)[a-zA-Z]*:\/\//i) // javascript: is not allowed, i for case insensitive (so Javascript: is also not allowed)
+  .refine((val) => !/^javascript:/i.test(val), "JavaScript URIs are not permitted")
   .or(z.literal(""))
   .transform((value) => (value.length === 0 ? null : value))
   .nullable();