chore: Add sample documentation #WPB-19997

docs/README.md

@@ -0,0 +1,87 @@
+
+# /docs 
+
+- These files are included in the `wire-docs` repository as a submodule and are pulled during the build process. They are essential for constructing the complete Wire documentation site. Any changes to these files should be made here, while updates to the older files (not present here anymore) should be committed directly to the `wire-docs` repository.
+
+![diagram](diagram.svg)
+
+- The Markdown (.md) pages in this directory should be self-contained, including any static images or diagrams. However, please note that links within these documents may not function correctly, as they are relative to the `wireapp/wire-docs/src` directory. To ensure that document links work as intended, collaborate with the `wire-docs` repository to identify their correct locations.
+
+- [build workflow](../.github/workflows/build.yaml):
+    - This workflow automates documentation validation between the `wire-apps-jvm-sdk` and `wire-docs` repositories. 
+
+    - When a PR is made to `wire-apps-jvm-sdk`'s main branch, GitHub Actions clones `wire-docs` and temporarily modifies its .gitmodules to point to the PR branch instead of develop. It then runs a build process to validate that the documentation changes work correctly with `wire-docs` symlink structure.
+
+    -  If validation passes, the workflow creates a second PR to `wire-docs` that updates the submodule reference to point to the specific commit ID from the original PR. 
+
+    - This dual-PR approach ensures that documentation changes are fully tested before being merged and maintains version stability by pinpointing exact commits rather than following branches.
+
+![build](build.svg)
+
+# Documentation Management for Wire
+
+## Understanding the Repository Structure
+- **wire-docs**: Main documentation repository
+- **wire-apps-jvm-sdk/docs**: Documentation related to the code in the `wire-apps-jvm-sdk` repository
+
+## Update Operations
+
+### Editing Existing Pages
+
+**For content in wire-apps-jvm-sdk/docs:**
+1. Make changes directly in the `wire-apps-jvm-sdk/docs` directory
+2. Create a PR against the `wire-apps-jvm-sdk:main` branch
+3. Once merged, these changes will be picked up by `wire-docs` through submodule updates
+
+**For content only in wire-docs:**
+1. Make changes directly in `wire-docs/src`
+2. Create a PR against `wire-docs:main` branch
+
+### Moving Pages from wire-docs/src to wire-apps-jvm-sdk/docs
+
+When a page needs to be moved because it's related to code changes:
+1. Add the page to `wire-apps-jvm-sdk/docs` and merge it to the main branch
+2. In `wire-docs`:
+   - Update the `wire-apps-jvm-sdk` submodule to the latest commit
+   - Delete the original page from `wire-docs/src`
+   - Create a relative symbolic link to the file in the `wire-apps-jvm-sdk` module:
+     ```
+     cd src/integrations/
+     rm creating-an-app.md
+     ln -s ../../../wire-apps-jvm-sdk/docs/src/creating-an-app.md creating-an-app.md
+     ```
+3. Test with `make run` before creating a PR
+
+## Creating New Files
+
+### For content related to wire-apps-jvm-sdk:
+1. Create the file in `wire-apps-jvm-sdk/docs`
+2. Merge it into `wire-apps-jvm-sdk:main`
+3. To make it discoverable on docs.wire.com:
+   - Update the navigation structure in [mkdocs.yml](https://github.com/wireapp/wire-docs/blob/main/mkdocs.yml#L9) or update the directory's README.md to include references to the new file, or add references to the new file from relevant existing pages
+   - Update the `wire-apps-jvm-sdk` submodule reference in `wire-docs` if not done automatically
+   - Add references to the new file from relevant existing pages
+   - Test with `make run` and create a PR to `wire-docs:main`
+
+### For content not related to wire-apps-jvm-sdk:
+1. Add the page to `wire-docs/src` in the appropriate location
+2. Update the navigation structure in [mkdocs.yml](https://github.com/wireapp/wire-docs/blob/main/mkdocs.yml#L9) or update the directory's README.md to include references to the new file, or add references to the new file from relevant existing pages 
+3. Test with `make run` and create a PR to `wire-docs:main`
+
+## Removing Files
+
+### Removing files from wire-apps-jvm-sdk/docs:
+1. Identify all references to the file in `wire-apps-jvm-sdk/docs` and `wire-docs`
+2. Remove all references and links from navigation (mkdocs.yml) and other pages
+3. Delete the file from its location
+4. Submit a PR to `wire-apps-jvm-sdk:main`
+
+### Removing files from wire-docs:
+1. Identify all references to the file in `wire-docs` and `wire-apps-jvm-sdk/docs`
+2. Remove all references and links from navigation (mkdocs.yml) and other pages
+3. Delete the file from its location
+4. Submit a PR to `wire-docs:main`
+
+## Publishing Changes
+
+All changes to documentation go live when the [CI Build](https://github.com/wireapp/wire-docs/blob/main/.github/workflows/build.yaml) workflow on `wire-docs` runs. Currently, submodule updates from `wire-apps-jvm-sdk` to `wire-docs` are performed manually, but there are plans to automate this with a pipeline.

docs/src/README.md

@@ -0,0 +1,50 @@
+# Understanding Apps
+
+Apps — sometimes called *integrations*, *services*, or *third-party applications* — are modular components that extend the platform without being part of its core codebase.
+
+## Key Characteristics
+- **Independent from core code**  
+  Apps are not bundled into the frontend or backend binaries. They live outside the main system.
+
+- **Pluggable and flexible**  
+  Apps can be added, updated, or removed without requiring a frontend/backend release.
+
+- **User-driven installation**  
+  Unlike system features that require admin deployment, apps can often be enabled (installed) directly by end users.
+
+- **Open for third parties**  
+  Apps are not limited to our company’s developers — external teams and third parties can build and operate their own apps.
+
+## How They Work
+Apps are separate pieces of software that communicate with the platform’s frontend and backend through a **common protocol** (such as APIs or events).  
+They remain independent, but can seamlessly interact with the system and its users.  
+
+An **App** is a way to extend and automate your team’s experience on Wire].
+Apps can listen to messages, send responses, and integrate with external services.
+
+## Why Apps?
+- **Automation**: Reduce manual tasks and streamline workflows.
+- **Integration**: Connect external systems (CRMs, support tools, monitoring).
+- **Customization**: Tailor the platform to your team’s needs.
+
+Apps are owned and managed at the **team level**, giving administrators control over:
+- Which Apps can be installed
+- What data Apps can access
+
+## How to create an App
+➡️ [Learn how to create an app](./creating-an-app.md)
+
+## SDK Overview
+
+We provide an official **Kotlin SDK** to help developers build apps quickly and safely.
+
+### Why use the SDK
+- Handles authentication for you
+- Provides event handling
+- Makes sending and receiving messages easier
+- Strongly typed for Kotlin developers
+
+### Future plans
+We currently support **Kotlin**, and plan to expand to more languages (JavaScript, Python, etc.) so every developer can build apps in the language they know best.
+
+For technical SDK usage and code examples, see the [Developer Documentation on GitHub](https://github.com/wireapp/wire-apps-jvm-sdk/blob/main/docs/APPLICATION.md).

docs/src/creating-an-app.md

@@ -0,0 +1,37 @@
+# Creating an App
+
+Creating an App is simple and only takes a few minutes.
+
+---
+
+## 1. Open the Team Settings Dashboard
+Go to Team Settings Dashboard and navigate to **Apps → Create New App**.
+
+![Team Settings Dashboard -> Apps -> Create New App](./images/create-app.png)
+
+---
+
+## 2. Choose a Name
+Pick a clear, descriptive name for your app.
+Example: `SupportBot`, `Daily Standup Assistant`.
+
+---
+
+## 3. Configure Permissions
+Apps require **permissions** (also called security scopes).  
+These define what your app can do.
+
+| Permission    | Common Use                           |
+|---------------|--------------------------------------|
+| `ALL`         | Can do everything a normal User can. |
+| `READ/WRITE`  | Utility Apps.                        |
+| `WRITE`       | Write only Apps.                     |
+
+To learn more about permissions, [click here](./permissions.md)
+
+---
+
+## 4. Generate an App Token
+Once created, your app will have a **unique token** used to authenticate requests.
+
+> 🔒 Treat tokens like passwords — never share them publicly.

docs/src/permissions.md

@@ -0,0 +1,15 @@
+# App Permissions
+
+Permissions define what your app is allowed to do inside the platform.
+
+### Permission Types:
+- **ALL**: Can do everything a normal User can.
+    - Reserved for legal hold, archival bots, etc. are permanently online and active. 
+- **READ/WRITE**: Utility Apps.
+    - Users interact with these Apps in limited ways, on demand using some command like /poll (in contrast to type 1). Think polls, summary bots, Jira integrations, confluence integrations.
+- **WRITE**: Utility Apps.
+    - Apps that notify you about things happening elsewhere and that need a very limited security scope. GitHub notifications, pager duty, jenkins bot, birthday bot. They do not receive messages.
+
+### Example Scenarios
+- A **reporting app** might need `READ/WRITE`.
+- A **standup bot** might only need `WRITE`.