Moved the setup and enterprise guides to the wiki (#1138)

2026-11-01 00:30:53 +00:00 · 2026-10-31 11:39:49 +01:00
1 parent aeba1fbccc
commit eef475581c
@@ -199,6 +199,28 @@ again yourself when `metadata.txt` changes during the session, e.g., after a mer
 - **Spaces in paths** - Always quote paths with spaces in bash commands
 - **Compatibility shims** - Temporary fallback or read-repair code must be documented in `documentation/compatibility-shims/` with an introduced date, remove-after date, code references, and removal checklist. Add a short code comment near the shim that references the document and remove-after date. Check this folder before adding similar fallback logic, and do not extend expired shims without explicit maintainer direction. Do not use this process for permanent settings schema migrations; those belong in `app/MindWork AI Studio/Settings/SettingsMigrations.cs`.

+## Wiki
+
+The documentation for users and IT departments lives in the wiki, https://github.com/MindWorkAI/AI-Studio/wiki:
+the user guide in US English and German, the Enterprise IT guides, and pages for developers. The files in
+`documentation/` are meant for contributors.
+
+- The wiki is a Git repository of its own, `MindWorkAI/AI-Studio.wiki`, with the folders `user-guide/` and
+  `de/` for the user guide, `enterprise/`, and `developers/`. GitHub renders only its `master` branch, and
+  only collaborators of the repository can change it.
+- A change which users or IT departments notice, such as a new assistant, a changed default, or a new
+  capability of configuration plugins, needs its wiki pages updated no later than the release which ships
+  it. When the wiki is cloned next to this repository, as `../AI-Studio.wiki`, change it there in commits of
+  its own. Otherwise, name the needed changes in the description of the pull request.
+- Mark what needs a certain version with "Requires AI Studio vX.Y.Z or newer": organizations take weeks
+  until every device runs a new version, so the pages describe several versions at once.
+- Write each page of the user guide in both languages, in the same commit; its first line links to the
+  other language. German pages use the wording of the de-de language plugin and the formal "Sie", like the
+  app.
+- GitHub shows the file name of a page as its title. Start a page without a `#` heading, keep commas out of
+  file names, and keep each name unique across all folders, because the URLs ignore them. Link pages as
+  `[[Text|Page-Name]]`, and list a new page in the `_Sidebar.md` of its folder; `de/` has its own.
+
 ## Changelogs
 Changelogs are located in `app/MindWork AI Studio/wwwroot/changelog/` with filenames `vX.Y.Z.md`. These changelogs are meant to be for normal end-users
 and should be written in a non-technical way, focusing on user-facing changes and improvements. Additionally, changes made regarding the plugin system
@@ -33,7 +33,7 @@ Are you new here? [Read here](#what-is-ai-studio) what AI Studio is.

 MindWork AI Studio is a free desktop app for macOS, Windows, and Linux. It provides a unified user interface for interaction with Large Language Models (LLM). AI Studio also offers so-called assistants, where prompting is not necessary. You can think of AI Studio like an email program: you bring your own API key for the LLM of your choice and can then use these AI systems with AI Studio. Whether you want to use Google Gemini, OpenAI GPT-6, or even your own local AI models.

-**Ready to get started 🤩?** [Download the appropriate setup for your operating system here](documentation/Setup.md).
+**Ready to get started 🤩?** [Download the appropriate setup for your operating system here](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio).

 **Key advantages:**
 - **Free of charge**: The app is free to use, both for personal and commercial purposes.
@@ -64,11 +64,11 @@ MindWork AI Studio is a free desktop app for macOS, Windows, and Linux. It provi
 - **Unrestricted usage**: Unlike services like ChatGPT, which impose limits after intensive use, MindWork AI Studio offers unlimited usage through the providers API.
 - **Cost-effective**: You only pay for what you use, which can be cheaper than monthly subscription services like ChatGPT Plus, especially if used infrequently. But beware, here be dragons: For extremely intensive usage, the API costs can be significantly higher. Unfortunately, providers currently do not offer a way to display current costs in the app. Therefore, check your account with the respective provider to see how your costs are developing. When available, use prepaid and set a cost limit.
 - **Privacy**: You can control which providers receive your data using the provider confidence settings. For example, you can set different protection levels for writing emails compared to general chats, etc. Additionally, most providers guarantee that they won't use your data to train new AI systems.
- **Enterprise IT**: Your IT department can manage AI Studio centrally: roll out providers, assistants, chat templates, and tools, set defaults, or lock settings for the whole organization. [Here's how it works.](documentation/Enterprise%20IT.md)
+- **Enterprise IT**: Your IT department can manage AI Studio centrally: roll out providers, assistants, chat templates, and tools, set defaults, or lock settings for the whole organization. [Here's how it works.](https://github.com/MindWorkAI/AI-Studio/wiki/Enterprise-IT)
 - **Flexibility**: Choose the provider and model best suited for your current task.
 - **No bloatware**: The app requires minimal storage for installation and operates with low memory usage. Additionally, it has a minimal impact on system resources, which is beneficial for battery life.

-## **Ready to get started 🤩?** [Download the appropriate setup for your operating system here](documentation/Setup.md).
+## **Ready to get started 🤩?** [Download the appropriate setup for your operating system here](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio).

 <details>
    <summary>
@@ -151,7 +151,7 @@ Did you find a security vulnerability? Please follow our [security policy](SECUR
    </h2>
    </summary>

-Do you want to manage AI Studio centrally from your IT department? Yes, that’s possible. [Here’s how it works.](documentation/Enterprise%20IT.md)
+Do you want to manage AI Studio centrally from your IT department? Yes, that’s possible. [Here’s how it works.](https://github.com/MindWorkAI/AI-Studio/wiki/Enterprise-IT)

 </details>

@@ -154,12 +154,13 @@ and the rules which are easy to break.
 ## Enterprise IT Support

 AI Studio supports centralized configuration for enterprise environments:
- **Registry (Windows)** or **environment variables** (all platforms) specify configuration server URL and ID
+- **Registry (Windows)**, **policy files**, or **environment variables** (all platforms) specify configuration server URL and ID
 - Configuration downloaded as ZIP containing Lua plugin
 - Checks for updates every ~16 minutes via ETag
 - Allows IT departments to pre-configure providers, settings, and chat templates

-**Documentation:** `documentation/Enterprise IT.md`
+**Documentation:** the Enterprise IT section of the wiki, https://github.com/MindWorkAI/AI-Studio/wiki/Enterprise-IT;
+see "Wiki" in the root `AGENTS.md`.

 ## Provider Confidence System

@@ -17,6 +17,9 @@ changelog entries.
 6. After PR merge, maintainer creates git tag: `vX.Y.Z`
 7. GitHub Actions builds release binaries for all platforms
 8. Binaries uploaded to GitHub Releases
+9. Update the wiki (`MindWorkAI/AI-Studio.wiki`): raise the version in `_Footer.md` and `de/_Footer.md`, and
+   check that the user guide and the Enterprise IT pages describe the release; see "Wiki" in the root
+   `AGENTS.md`

 ## Crediting contributors

@@ -65,7 +65,7 @@

        <MudJustifiedText Typo="Typo.body2" Class="mb-3">
            @T("Generate a 256-bit encryption secret for encrypting API keys in configuration plugins. Deploy this secret to client machines via Group Policy (Windows Registry) or environment variables. Providers can then be exported with encrypted API keys using the export buttons in the provider settings.")
-            <MudLink Href="https://github.com/MindWorkAI/AI-Studio/blob/main/documentation/Enterprise%20IT.md" Target="_blank">
+            <MudLink Href="https://github.com/MindWorkAI/AI-Studio/wiki/Enterprise-IT" Target="_blank">
                @T("Read the Enterprise IT documentation for details.")
            </MudLink>
        </MudJustifiedText>
@@ -40,7 +40,7 @@ When adding configuration plugin capabilities:
 - For managed settings, update the corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)` and process the setting in `PluginConfiguration.TryProcessConfiguration`. Cleaning up the setting when its configuration plugin was removed needs no extra step: `ManagedConfiguration.CleanupLeftOverManagedConfigurations(...)` iterates all registered settings. Do not add per-setting cleanup calls to `PluginFactory.Loading.LoadAll`. `ManagedSettingsCoverageTests` fails for a registered setting which no configuration plugin can manage; a setting which must stay out of their reach goes into its list `EXEMPT_SETTINGS`, together with the reason.
 - For managed configuration objects, add the type to `PluginConfigurationObjectType.cs`, persist the objects in the appropriate `ConfigurationData` collection, and add a descriptor to `PluginConfigurationObjectDescriptors` and its list `ALL`: its Lua table, its parser, the collection, the next number, and where secrets are kept. Parsing and cleanup need no extra call; `PluginConfigurationObjectDescriptorsTests` fails for a type without a descriptor.
 - For live plugin content, add a data type implementing `ILivePluginContent`, parse it in `PluginConfiguration`, expose it through `PluginFactory`, and add any required cleanup only for persistent side data.
- Always document the new capability in `app/MindWork AI Studio/Plugins/configuration/plugin.lua`.
+- Always document the new capability in `app/MindWork AI Studio/Plugins/configuration/plugin.lua`, the reference of every setting, and explain it on the matching Enterprise IT page of the wiki, marked with the version which brings it; see "Wiki" in the root `AGENTS.md`.

 ## Importing exported configuration objects

@@ -1,5 +1,6 @@
 # v26.11.1, build 260 (2026-11-xx xx:xx UTC)
 - Added a setting for the size of the interface, which you find in the app settings. You can choose a size for each of your screens, and AI Studio switches to it when you move its window to another screen. Thanks, Paul Koudelka (`PaulKoudelka`), for this contribution.
+- Improved the documentation for IT departments, which now lives in our [wiki](https://github.com/MindWorkAI/AI-Studio/wiki/Enterprise-IT). It is sorted by task, explains the setup on Windows, Linux, and macOS, and offers complete configurations for typical needs, such as using only local models. The link in the app settings leads there, and the wiki also holds the installation guide in English and German.
 - Changed the size of AI Studio on laptop screens: it now appears in the same size on every laptop, whatever the scaling of your operating system. If you prefer the previous size, choose "System scaling" for the interface size in the app settings. Contributed by Paul Koudelka.
 - Fixed AI Studio becoming unusable when an update failed after its download. The app now restarts with the version you have installed, so you can simply try the update again.
 - Upgraded several libraries to improve security.
@@ -1,5 +1,5 @@
 # Building
-You just want to use the app? Then simply [download the appropriate setup for your operating system](Setup.md). This chapter is intended for developers who want to modify and customize the code.
+You just want to use the app? Then simply [download the appropriate setup for your operating system](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio). This chapter is intended for developers who want to modify and customize the code.

 ## Prefaces regarding Linux development systems
 Unfortunately, we have to provide a note regarding development on Linux systems. MindWork AI Studio consists of a Rust and a .NET part. Compiling the .NET code works smoothly on all operating systems. However, this is not the case for our Rust part. More specifically, it is not the Rust code itself that is problematic, but rather the Tauri framework on which we base our work. Tauri has certain dependencies that depend on the operating system. The specific dependencies vary between different Linux distributions and between versions of distributions.
@@ -104,7 +104,7 @@ Two surfaces, and they answer different questions:
 - **A model plugin** (`PluginType.MODEL`) describes a model wherever it is reached — a fine-tune of your own, a model behind an internal name. It only describes: no endpoint, no key, no code. `app/MindWork AI Studio/Plugins/models/plugin.lua` documents every key with examples.
 - **`CapabilityOverrides` on an LLM provider** in a configuration plugin describes **this one installation** of a model. This is the right place for the window an operator actually configured, as opposed to the one the model card advertises.

-Both are documented for administrators in `documentation/Enterprise IT.md`. Model plugins are deployed, not imported: a user cannot install one themselves.
+Both are documented for administrators on the wiki page [Providers and API Keys](https://github.com/MindWorkAI/AI-Studio/wiki/Providers-and-API-Keys#describing-your-own-models). Model plugins are deployed, not imported: a user cannot install one themselves.

 ## Live Metadata From The Model Lists

@@ -1,168 +1,23 @@
 # Install the app
-To get started, choose your operating system where you want to install the app:

- [Windows](#windows)
- [macOS](#macos)
- [Linux](#linux)
+The installation guide has moved to our wiki: [Installing AI Studio](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio). A German version is available as well: [AI Studio installieren](https://github.com/MindWorkAI/AI-Studio/wiki/AI-Studio-installieren).
+
+This page stays so that existing links keep working. Each former section below points to its new place.

 ## Windows
-AI Studio is only available for modern 64-bit Windows systems. When you have an older 32-bit system, you won't be able to run the app. We require an updated Windows 10 or 11 version; the app won't properly work on Windows 7 or 8. Next, we have to figure out if you have an Intel/AMD or a modern ARM system on your Windows machine.
-
- **Copilot+ PC:** Do you own one of the new Copilot+ PCs? If so, you most likely have an ARM system. When your machine has a Qualcomm sticker on it, you have an ARM system for sure. [Download the ARM version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_arm64-setup.exe) of AI Studio.
- 
- **Windows on macOS:** Do you run Windows using Parallels on an Apple Silicon system (M1, M2, M3, M4)? Then you have an ARM system as well. [Download the ARM version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_arm64-setup.exe) of AI Studio.
-
- **Intel/AMD:** In almost all other cases, you have an Intel/AMD system. [Download the x64 version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_x64-setup.exe) of AI Studio.
-
-Our installer is signed, so Windows can show that it comes from us. Because our certificate is still new, Windows may nevertheless warn you for a while when you start the installer. In that case, click on "More info":
-
-![Windows Protection 1](Windows%20Warning%201.png)
-
-Check that the publisher ends with "Open Source Developer Thorsten Sommer". Then click on "Run anyway" to proceed with the installation:
-
-![Windows Protection 2](Windows%20Warning%202.png)
-
-When the publisher reads "Unknown publisher" or names somebody else, do not run the installer. Download it again from our [release page](https://github.com/MindWorkAI/AI-Studio/releases/latest) instead. There, we also provide VirusTotal scan results for each release.
-
-Signing AI Studio for Windows and macOS costs us around €150 per year. Would you like to help us with this? [Please consider supporting us](https://github.com/sponsors/MindWorkAI).
-
-Once the app is installed, it will check for updates automatically. If a new version is available, you will be prompted to install it.
+See [Windows](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#windows).

 ## macOS
-AI Studio is available for modern 64-bit macOS systems. The minimum requirement is macOS 10.13 (High Sierra). Next, we have to figure out if you have an Intel or a modern Apple Silicon (ARM) system.
-
- **Apple Silicon:** Do you have a modern Apple Silicon system (M1, M2, M3, M4)?  [Download the ARM version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_aarch64.dmg) of AI Studio.
-
- **Time of purchase:** Did you buy your Mac in 2021 or later? Then you probably have an ARM system. [Download the ARM version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_aarch64.dmg) of AI Studio.
-
- **Check System Information:** On your macOS, click on the Apple logo in the top left corner, then "About This Mac." In the window that opens, you can see the processor type. When it says "Apple M1" or similar, you have an ARM system. [Download the ARM version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_aarch64.dmg) of AI Studio.
-
- **Intel:** Older Macs have an Intel processor. [Download the Intel version](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/MindWork.AI.Studio_x64.dmg) of AI Studio.
-
-After downloading the file, open the DMG file and drag the app to your Applications folder:
-
-![macOS Installation 1](macOS%20Mount.png)
-
-When you open the app for the first time, macOS asks whether you want to open an app downloaded from the internet. AI Studio is signed and checked by Apple, so you can confirm with "Open". Afterward, the app starts like any other app.
-
-Signing AI Studio for Windows and macOS costs us around €150 per year. Would you like to help us with this? [Please consider supporting us](https://github.com/sponsors/MindWorkAI).
-
-Once the app is installed, it will check for updates automatically. If a new version is available, you will be prompted to install it.
+See [macOS](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#macos).

 ## Linux
-MindWork AI Studio is available for modern 64-bit Linux systems. Starting with release v26.7.3, Flatpak is the recommended installation method. We test AI Studio on Ubuntu 24.04 and 26.04, Kubuntu 24.04, Fedora 43 or newer, and openSUSE Leap 16 or newer, but it should work on other distributions as well.
-
-First, determine whether your system uses the Intel/AMD or ARM architecture:
-
-```bash
-uname -m
-```
-
-`x86_64` means Intel/AMD; `aarch64` means ARM.
+See [Linux](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#linux).

 ### Recommended: Flatpak Installation
-
-On Ubuntu, install Flatpak first:
-
-```bash
-sudo apt update
-sudo apt install flatpak
-```
-
-For other Linux distributions, follow the [official Flatpak setup instructions](https://flatpak.org/setup/).
-
-Open the [latest AI Studio release](https://github.com/MindWorkAI/AI-Studio/releases/latest) and download the bundle for your architecture:
-
- **Intel/AMD (`x86_64`):** `MindWork.AI.Studio_x86_64.flatpak`
- **ARM (`aarch64`):** `MindWork.AI.Studio_aarch64.flatpak`
-
-Install the downloaded bundle for your user account. For Intel/AMD, run:
-
-```bash
-cd ~/Downloads
-flatpak install --user ./MindWork.AI.Studio_x86_64.flatpak
-```
-
-For ARM, run:
-
-```bash
-cd ~/Downloads
-flatpak install --user ./MindWork.AI.Studio_aarch64.flatpak
-```
-
-Confirm the installation of the required GNOME runtime from Flathub when Flatpak asks for it.
-
-#### Pandoc Extension (Strongly Recommended)
-
-Pandoc is required for some file features, namely attaching HTML files and exporting chats as a Word document. Every other file type, PDFs, Word and OpenDocument text files, spreadsheets, and presentations among them, is read by AI Studio itself and works without Pandoc. We still recommend installing the Pandoc extension so that all file features are available. AI Studio checks whether a compatible Pandoc version is already available.
-
-For Intel/AMD, download `MindWork.AI.Studio.Plugin.Pandoc_x86_64.flatpak` and run:
-
-```bash
-cd ~/Downloads
-flatpak install --user ./MindWork.AI.Studio.Plugin.Pandoc_x86_64.flatpak
-```
-
-For ARM, download `MindWork.AI.Studio.Plugin.Pandoc_aarch64.flatpak` and run:
-
-```bash
-cd ~/Downloads
-flatpak install --user ./MindWork.AI.Studio.Plugin.Pandoc_aarch64.flatpak
-```
-
-#### Starting and Updating the Flatpak
-
-Start AI Studio from your application menu or run:
-
-```bash
-flatpak run org.mindworkai.AIStudio
-```
-
-If no application-menu entry appears, sign out of your desktop session completely and sign in again, or restart the system.
-
-Until AI Studio is published on Flathub, bundles installed from GitHub do not receive automatic app updates. Download each new bundle and reinstall it. For Intel/AMD, run:
-
-```bash
-cd ~/Downloads
-flatpak install --user --reinstall ./MindWork.AI.Studio_x86_64.flatpak
-```
-
-Use `MindWork.AI.Studio_aarch64.flatpak` instead on ARM.
+See [Recommended: Flatpak](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#recommended-flatpak).

 ### Alternative: AppImage Installation
-
-If you prefer not to use Flatpak, AI Studio is also available as an AppImage:
-
- **Intel/AMD:** [Download the Intel/AMD AppImage](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/mind-work-ai-studio_amd64.AppImage).
- **ARM:** [Download the ARM AppImage](https://github.com/MindWorkAI/AI-Studio/releases/latest/download/mind-work-ai-studio_aarch64.AppImage).
-
-**Prepare the AppImage using the desktop environment:**
-1. Download the AppImage from the link above.
-2. Open your file manager and navigate to the Downloads folder.
-3. Right-click on the AppImage and select "Properties":
-   ![Ubuntu Installation 4](Ubuntu%20AppImage%20Properties.png)
-4. Go to the "Permissions" tab and check the box "Allow executing file as program":
-   ![Ubuntu Installation 5](Ubuntu%20AppImage%20Permissions.png)
-5. Close the property window.
-6. You might want to move the AppImage to a more convenient location, e.g., your home directory.
-7. Double-click the AppImage to run it.
-
-**Prepare the AppImage using the terminal:**
-1. Download the AppImage from the link above.
-2. Open a terminal and navigate to the Downloads folder: `cd ~/Downloads`.
-3. Make the AppImage executable: `chmod +x mind-work-ai-studio_amd64.AppImage`.
-4. You might want to move the AppImage to a more convenient location, e.g., your home directory: `mv mind-work-ai-studio_amd64.AppImage ~/`.
-5. Now you can run the AppImage from your file manager (double-click) or the terminal: `~/mind-work-ai-studio_amd64.AppImage`.
-
-Use the `aarch64` file name instead of the `amd64` file name on ARM systems.
+See [Alternative: AppImage](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#alternative-appimage).

 ### Secure Storage for API Keys
-
-On Linux, AI Studio stores API keys through the FreeDesktop Secret Service API. A compatible password manager must provide this service, and it must have an unlocked default collection. AI Studio never creates, selects, unlocks, or changes a password manager's default collection itself.
-
-Compatible configurations include:
-
- GNOME Keyring, which can be managed with an application such as Seahorse. Create a password collection if necessary, unlock it, and choose **Set as default**.
- KeePassXC with Secret Service integration enabled and a database group exposed to the service. Keep the relevant database and group unlocked when AI Studio needs to access secrets.
-
-Automatic login can prevent GNOME Keyring from being unlocked automatically. If secure storage remains locked after login, unlock the default collection in your password manager.
+See [Secure storage for API keys](https://github.com/MindWorkAI/AI-Studio/wiki/Installing-AI-Studio#secure-storage-for-api-keys).