docs(plugins): document plugin and permission identifier syntax rules - #3826

src/content/docs/develop/Plugins/index.mdx

@@ -32,6 +32,31 @@ Tauri plugins have a prefix followed by the plugin name. The plugin name is spec
 
 By default Tauri prefixes your plugin crate with `tauri-plugin-`. This helps your plugin to be discovered by the Tauri community and to be used with the Tauri CLI. When initializing a new plugin project, you must provide its name. The generated crate name will be `tauri-plugin-{plugin-name}` and the JavaScript NPM package name will be `tauri-plugin-{plugin-name}-api` (although we recommend using an [NPM scope](https://docs.npmjs.com/about-scopes) if possible). The Tauri naming convention for NPM packages is `@scope-name/plugin-{plugin-name}`.
 
+### Identifier Rules
+
+The `{plugin-name}` portion of a plugin crate, and any permission identifier referenced within capabilities, must follow Tauri's identifier syntax:
+
+- Lowercase ASCII letters (`a` through `z`), digits (`0` through `9`), and hyphens (`-`).
+- Hyphens cannot appear as the first or last character.
+- A single colon (`:`) is permitted only when the identifier uses a prefix (for example `<plugin-name>:<permission-name>`).
+- Underscores (`_`), uppercase letters, and other characters are not allowed.
+- The base name is limited to 64 characters; with a prefix, the full identifier is limited to 129 characters.
+
+Examples:
+
+| Identifier                |         Valid?          |
+| ------------------------- | :---------------------: |
+| `sqlite`                  |            ✓            |
+| `sqlite-store`            |            ✓            |
+| `sqlite-store:allow-read` |            ✓            |
+| `sqlite_store`            |     ✗ (underscore)      |
+| `SqliteStore`             |      ✗ (uppercase)      |
+| `-sqlite`                 |   ✗ (leading hyphen)    |
+| `sqlite-`                 |   ✗ (trailing hyphen)   |
+| `sqlite::store`           | ✗ (multiple separators) |
+
+If a plugin or permission identifier violates these rules, the build fails with the error `identifiers can only include lowercase ASCII, hyphens which are not leading or trailing, and a single colon if using a prefix`. The offending value is usually the plugin name in your plugin's `Cargo.toml` or a permission identifier in a `permissions/*.toml` file.
+
 ## Initialize Plugin Project
 
 To bootstrap a new plugin project, run `plugin new`. If you do not need the NPM package, use the `--no-api` CLI flag. If you want to initialize the plugin with Android and/or iOS support, use the `--android` and/or `--ios` flags.