docs(plugin): rewrite architecture + template for the external-only model

OpenCADStudio ships no built-in plugins, so the spec and scaffold no
longer describe the in-tree inventory path, demo_plugin, or the fictional
Storm Sewer reference. The architecture doc now covers the external cdylib
model end to end (ocs_plugin_api contract, export_plugin!, building +
publishing per-platform releases, runtime loading, the marketplace +
curated registry, the approach-B ABI caveat). The template becomes a
standalone cdylib crate (Cargo.toml + src/lib.rs + release workflow)
instead of an in-tree module.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/plugin-template/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: release
+
+# Build the plugin cdylib for each desktop platform and attach the binaries
+# (plus plugin.toml) to a GitHub Release on a v* tag. Open CAD Studio's Plugin
+# Manager reads the assets, picks the one matching the user's OS/arch, and
+# installs it. Rename the `asset:` files to your plugin id.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            ext: so
+            asset: opencad.my_plugin-linux-x86_64.so
+          - os: windows-latest
+            ext: dll
+            asset: opencad.my_plugin-windows-x86_64.dll
+          - os: macos-latest
+            ext: dylib
+            asset: opencad.my_plugin-macos-aarch64.dylib
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo build --release
+      - name: Stage release asset
+        shell: bash
+        run: |
+          mkdir -p dist
+          cp target/release/*.${{ matrix.ext }} "dist/${{ matrix.asset }}"
+          cp plugin.toml dist/plugin.toml
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/${{ matrix.asset }}
+            dist/plugin.toml

docs/plugin-template/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "my-plugin"
+version = "0.1.0"
+edition = "2021"
+description = "An Open CAD Studio add-on."
+license = "GPL-3.0-only"
+
+# A plugin is a C-ABI dynamic library the host loads at runtime.
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+# The stable contract, with the runtime `host` surface (HostApi / BuiltinPlugin).
+ocs_plugin_api = { git = "https://github.com/HakanSeven12/OpenCADStudio", features = ["host"] }
+
+# Match the host's acadrust so the loaded library is binary-compatible
+# (approach B assumes the same toolchain + dependency versions).
+[patch.crates-io]
+acadrust = { git = "https://github.com/HakanSeven12/acadrust", branch = "main" }

docs/plugin-template/README.md

@@ -1,31 +1,47 @@
-# Add-on plugin template
+# Open CAD Studio plugin template
 
-Copy this folder to `src/modules/<your_module>/` and rename placeholders.
+A complete scaffold for an **external** Open CAD Studio add-on. A plugin is its
+own repository that builds a `cdylib`; the host loads it at runtime. Copy this
+folder into a new repo and rename the placeholders.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Cargo.toml` | `cdylib` crate depending on `ocs_plugin_api` (`host` feature) |
+| `src/lib.rs` | manifest + `CadModule` ribbon + `BuiltinPlugin` + `export_plugin!` |
+| `plugin.toml` | metadata read by the host (mirrors the manifest) |
+| `.github/workflows/release.yml` | cross-builds the cdylib and publishes a release |
+| `PLUGIN.md` | your command reference + XDATA schemas |
 
 ## Quick start
 
-1. Copy files into `src/modules/my_plugin/`.
-2. Replace `MY_PLUGIN`, `my_plugin`, `opencad.my_plugin`, `MP_` throughout.
-3. Add `pub mod my_plugin;` to `src/modules/mod.rs`.
-4. `cargo build` — ribbon tab and commands register automatically.
+1. Copy this folder into a new repository.
+2. Rename `my-plugin` / `My Plugin` / `opencad.my_plugin` / `my_plugin` / `MP_`
+   throughout (`Cargo.toml`, `src/lib.rs`, `plugin.toml`, the workflow `asset:`
+   names), keeping `plugin.toml` and the `MANIFEST` in sync.
+3. `cargo build` to check it compiles.
 
-## Required files
+## Test locally
 
-| File | Purpose |
-|------|---------|
-| `plugin.toml` | Metadata (QGIS-style); excludes dir from `build.rs` ribbon scan |
-| `manifest.rs` | Compile-time `PluginManifest` — keep in sync with `plugin.toml` |
-| `register.rs` | `inventory::submit!(PluginRegistration { … })` only |
-| `plugin.rs` | Thin `BuiltinPlugin` impl |
-| `dispatch.rs` | All command handlers |
-| `mod.rs` | `CadModule` ribbon + `CommandRegistration` for autocomplete |
-| `PLUGIN.md` | XDATA schemas and command reference |
+```sh
+cargo build --release
+mkdir -p "<config>/OpenCADStudio/plugins/opencad.my_plugin"
+cp target/release/*my_plugin*.so "<config>/OpenCADStudio/plugins/opencad.my_plugin/"
+cp plugin.toml                    "<config>/OpenCADStudio/plugins/opencad.my_plugin/"
+```
 
-## Optional
+Restart Open CAD Studio: the ribbon tab appears and `MP_` commands route to your
+plugin. (`<config>` = `%APPDATA%` / `~/Library/Application Support` /
+`$XDG_CONFIG_HOME`.)
 
-| File | Purpose |
-|------|---------|
-| `state.rs` | Per-document tab state via `host.ensure_plugin_state(PLUGIN_ID, …)` |
-| `crates/my_engine/` | Headless domain logic (no iced/acadrust) |
+## Publish
 
-See `docs/plugin-architecture.md` for the full spec.
+Push a `v*` tag — the workflow builds the cdylib on Linux/Windows/macOS and
+uploads each binary plus `plugin.toml` to a GitHub Release. Users install it from
+the **Plugin Manager** by linking your `owner/repo`, or — once your repo is added
+to [`plugins/registry.json`](https://github.com/HakanSeven12/OpenCADStudio/blob/main/plugins/registry.json)
+via PR — straight from *Available plugins*.
+
+> The binary must be built with the same toolchain and `ocs_plugin_api` version
+> as the host (approach B). See `docs/plugin-architecture.md`.

docs/plugin-template/dispatch.rs

@@ -1,14 +0,0 @@
-use crate::plugin::host::HostApi;
-
-use super::manifest::PLUGIN_ID;
-
-pub fn handle(host: &mut dyn HostApi, cmd: &str) -> bool {
-    let _ = (host, PLUGIN_ID);
-    match cmd {
-        "MP_HELLO" => {
-            host.push_info("Hello from my_plugin");
-            true
-        }
-        _ => false,
-    }
-}

docs/plugin-template/manifest.rs

@@ -1,14 +0,0 @@
-use crate::plugin::manifest::{ApiVersion, PluginManifest};
-
-pub const PLUGIN_ID: &str = "opencad.my_plugin";
-
-pub static MANIFEST: PluginManifest = PluginManifest {
-    id: PLUGIN_ID,
-    name: "My Plugin",
-    version: "0.1.0",
-    description: "Short description of what this add-on does",
-    api_version: ApiVersion::CURRENT,
-    ribbon_order: 60,
-    xdata_apps: &["MYPLUGIN_RECORD"],
-    command_prefixes: &["MP_"],
-};

docs/plugin-template/mod.rs

@@ -1,34 +0,0 @@
-pub mod dispatch;
-pub mod manifest;
-pub mod plugin;
-pub mod register;
-
-use crate::modules::{CadModule, IconKind, ModuleEvent, RibbonGroup, RibbonItem, ToolDef};
-
-inventory::submit!(crate::command::CommandRegistration {
-    names: &["MP_HELLO"]
-});
-
-pub struct MyPluginModule;
-
-impl CadModule for MyPluginModule {
-    fn id(&self) -> &'static str {
-        "my_plugin"
-    }
-
-    fn title(&self) -> &'static str {
-        "My Plugin"
-    }
-
-    fn ribbon_groups(&self) -> Vec<RibbonGroup> {
-        vec![RibbonGroup {
-            title: "Tools",
-            tools: vec![RibbonItem::LargeTool(ToolDef {
-                id: "MP_HELLO",
-                label: "Hello",
-                icon: IconKind::Glyph("★"),
-                event: ModuleEvent::Command("MP_HELLO".to_string()),
-            })],
-        }]
-    }
-}

docs/plugin-template/plugin.rs

@@ -1,21 +0,0 @@
-use crate::plugin::host::{BuiltinPlugin, HostApi};
-use crate::plugin::manifest::PluginManifest;
-
-use super::dispatch;
-use super::manifest;
-
-pub struct MyPlugin;
-
-impl BuiltinPlugin for MyPlugin {
-    fn manifest(&self) -> &'static PluginManifest {
-        &manifest::MANIFEST
-    }
-
-    fn ribbon(&self) -> Box<dyn crate::modules::CadModule> {
-        Box::new(super::MyPluginModule)
-    }
-
-    fn dispatch(&self, host: &mut dyn HostApi, cmd: &str) -> bool {
-        dispatch::handle(host, cmd)
-    }
-}

docs/plugin-template/register.rs

@@ -1,7 +0,0 @@
-use super::plugin::MyPlugin;
-
-inventory::submit! {
-    crate::plugin::registry::PluginRegistration {
-        construct: || Box::new(MyPlugin),
-    }
-}

docs/plugin-template/src/lib.rs

@@ -0,0 +1,68 @@
+//! Open CAD Studio add-on template.
+//!
+//! Rename the crate (`Cargo.toml`), the ids/strings below, and `plugin.toml` to
+//! match. Build with `cargo build --release` and ship the resulting cdylib plus
+//! `plugin.toml` as GitHub Release assets (see `.github/workflows/release.yml`).
+
+use ocs_plugin_api::host::{BuiltinPlugin, HostApi};
+use ocs_plugin_api::manifest::{ApiVersion, PluginManifest};
+use ocs_plugin_api::ribbon::{CadModule, IconKind, ModuleEvent, RibbonGroup, RibbonItem, ToolDef};
+
+// Keep these fields in sync with `plugin.toml`.
+static MANIFEST: PluginManifest = PluginManifest {
+    id: "opencad.my_plugin",
+    name: "My Plugin",
+    version: "0.1.0",
+    description: "What this plugin does.",
+    api_version: ApiVersion::CURRENT,
+    ribbon_order: 50,
+    xdata_apps: &[],
+    command_prefixes: &["MP_"],
+};
+
+/// The ribbon tab.
+struct MyModule;
+
+impl CadModule for MyModule {
+    fn id(&self) -> &'static str {
+        "my_plugin"
+    }
+    fn title(&self) -> &'static str {
+        "My Plugin"
+    }
+    fn ribbon_groups(&self) -> Vec<RibbonGroup> {
+        vec![RibbonGroup {
+            title: "Tools",
+            tools: vec![RibbonItem::LargeTool(ToolDef {
+                id: "MP_HELLO",
+                label: "Hello",
+                icon: IconKind::Glyph("★"),
+                event: ModuleEvent::Command("MP_HELLO".to_string()),
+            })],
+        }]
+    }
+}
+
+/// The plugin entry point.
+struct MyPlugin;
+
+impl BuiltinPlugin for MyPlugin {
+    fn manifest(&self) -> &'static PluginManifest {
+        &MANIFEST
+    }
+    fn ribbon(&self) -> Box<dyn CadModule> {
+        Box::new(MyModule)
+    }
+    fn dispatch(&self, host: &mut dyn HostApi, cmd: &str) -> bool {
+        match cmd {
+            "MP_HELLO" => {
+                host.push_info("Hello from My Plugin");
+                true
+            }
+            _ => false,
+        }
+    }
+}
+
+// Emit the C-ABI symbols the host loader looks for.
+ocs_plugin_api::export_plugin!(MyPlugin);