sync

docs/contributing.mdx

@@ -3,111 +3,97 @@ sidebar_position: 1600
 title: "🤝 Contributing"
 ---
 
+# 🤝 Contributing
 
-🚀 **Welcome, Contributors!** 🚀
+**Help build the AI interface everyone deserves.**
 
-Your interest in contributing to Open WebUI is greatly appreciated. This document is here to guide you through the process, ensuring your contributions enhance the project effectively. Let's make Open WebUI even better, together!
+Open WebUI is an independent project built and maintained by a small, dedicated core team. Whether you test dev builds, fix bugs, improve docs, or translate the UI, every contribution makes the project better for thousands of users. This page explains how to get involved and what to expect.
 
-## 📜 Code of Conduct
+---
+
+## Code of Conduct
 
-All contributors and community participants are expected to follow our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy** — disrespectful, demanding, or hostile behavior will result in immediate action without prior warning.
+All contributors and community participants must follow the **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy**: disrespectful, demanding, or hostile behavior results in immediate action without prior warning.
 
-Our community is built on the work of volunteers who dedicate their free time to this project. Please treat every interaction with professionalism and respect.
+This project is built by volunteers in their free time. Treat every interaction with professionalism and respect.
 
-## 💡 Contributing
+---
 
-Looking to contribute? Great! Here's how you can help:
+## Ways to Contribute
 
-### 🧪 Test the Development Branch
+### Test the development branch
 
-**One of the most valuable ways to contribute is running the dev branch.** You don't need to write code—just use it and report issues!
+One of the most valuable contributions requires no code at all. Run the dev branch, use it daily, and report what breaks.
 
 ```bash
 docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev
 ```
 
-**Keep it updated regularly** — the dev branch moves fast! If Docker doesn't work for you, the [Local Development Guide](/getting-started/development) is another great option.
-
-By testing dev builds, you help us catch bugs before stable releases. Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. **We cannot deliver high-quality releases without community testing.**
-
-### 🌟 Code Contribution Guidelines
+The dev branch moves fast, so **pull updates regularly**. If Docker is not your preference, follow the [Local Development Guide](/getting-started/advanced-topics/development) instead.
 
-We welcome pull requests. Before submitting one, please:
+Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. We cannot deliver high-quality releases without community testing.
 
-1. Open a discussion regarding your ideas [here](https://github.com/open-webui/open-webui/discussions/new/choose).
-2. Follow the project's coding standards and include tests for new features.
-3. Update documentation as necessary.
-4. Write clear, descriptive commit messages.
+### Submit code
 
-### 🛠 Code PR Best Practices:
+We welcome pull requests. Before submitting one:
 
-1. **Atomic PRs:** Make sure your PRs are small, focused, and deal with a single objective or task. This helps in easier code review and limits the chances of introducing unrelated issues. If the scope of changes grows too large, consider breaking them into smaller, logically independent PRs.
-2. **Follow Existing Code Convention:** Ensure your code aligns with the existing coding standards and practices of the project.
-3. **Avoid Additional External Dependencies:** Do not include additional external dependencies without prior discussion.
-4. **Framework Agnostic Approach:** We aim to stay framework agnostic. Implement functionalities on our own whenever possible rather than relying on external frameworks or libraries. If you have doubts or suggestions regarding this approach, feel free to discuss it.
+1. **Open a discussion first.** Propose your idea [here](https://github.com/open-webui/open-webui/discussions/new/choose) so the team can align on approach before you write code.
+2. **Follow existing conventions.** Match the project's coding standards, naming patterns, and architecture.
+3. **Keep PRs atomic.** Each pull request should address a single objective. If scope grows, split it into smaller, logically independent PRs.
+4. **Avoid new external dependencies.** Do not add libraries or frameworks without prior discussion. We aim to stay framework-agnostic and implement functionality ourselves when practical.
+5. **Include tests.** Cover new features with tests and update documentation as needed.
+6. **Write clear commit messages.** Descriptive messages make review and history tracking easier.
 
-Thank you for contributing! 🚀
+### Improve documentation
 
-### 📚 Documentation & Tutorials
+Help make Open WebUI more accessible by improving docs, writing tutorials, or creating setup guides. Documentation lives in the [docs repository](https://github.com/open-webui/docs).
 
-Help us make Open WebUI more accessible by improving documentation, writing tutorials, or creating guides on setting up and optimizing the web UI.
+### Translate the UI
 
-### 🌐 Translations and Internationalization
-
-Help us make Open WebUI available to a wider audience. In this section, we'll guide you through the process of adding new translations to the project.
-
-We use JSON files to store translations. You can find the existing translation files in the `src/lib/i18n/locales` directory. Each directory corresponds to a specific language, for example, `en-US` for English (US), `fr-FR` for French (France) and so on. You can refer to [ISO 639 Language Codes](http://www.lingoes.net/en/translator/langcode.htm) to find the appropriate code for a specific language.
+Open WebUI uses JSON translation files in `src/lib/i18n/locales`. Each subdirectory is named with an [ISO 639 language code](http://www.lingoes.net/en/translator/langcode.htm) (e.g., `en-US`, `fr-FR`).
 
 To add a new language:
 
-- Create a new directory in the `src/lib/i18n/locales` path with the appropriate language code as its name. For instance, if you're adding translations for Spanish (Spain), create a new directory named `es-ES`.
-- Copy the American English translation file(s) (from `en-US` directory in `src/lib/i18n/locale`) to this new directory and update the string values in JSON format according to your language. Make sure to preserve the structure of the JSON object.
-- Add the language code and its respective title to languages file at `src/lib/i18n/locales/languages.json`.
-
-### 🌎 Accessibility Matters
-
-We are committed to making **Open WebUI** inclusive and usable for everyone. Accessibility is a core part of good system design.
-
-Here’s how you can help improve accessibility when you contribute:
+1. Create a new directory under `src/lib/i18n/locales` named with the appropriate language code
+2. Copy the `en-US` translation files into the new directory
+3. Translate the string values in each JSON file while preserving the object structure
+4. Register the language in `src/lib/i18n/locales/languages.json`
 
-- **Semantic HTML**: Use semantic HTML elements (`<button>`, `<label>`, `<nav>`, etc.) to ensure screen readers and other assistive technologies can properly interpret the interface.
-- **Keyboard Navigation**: Ensure all interactive elements are fully usable with a keyboard. Avoid mouse-only interactions.
-- **ARIA Labels**: When necessary, use appropriate [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) roles and labels to enhance accessibility, but do not replace semantic html with roles and labels.
-- **Color Contrast & Visual Indicators**: Use high-contrast colors and ensure visual indicators, like focus states, are clear. You can use tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your changes.
-- **Alt Text for Images**: Provide descriptive `alt` text for images and icons when they convey meaning, but equally important, if the image convays no information and is decorative in nature, use an empty alt text (`alt=""`).
+### Improve accessibility
 
-To test you changes, you can use tools like lighthouse or the accessibility tools in your browser.
+Accessibility is a core part of good design. When contributing UI changes:
 
-Let's make Open WebUI usable for *everyone*.
+| Principle | What to do |
+|-----------|-----------|
+| **Semantic HTML** | Use `<button>`, `<label>`, `<nav>`, and other semantic elements instead of generic `<div>` wrappers |
+| **Keyboard navigation** | Ensure all interactive elements work without a mouse |
+| **ARIA labels** | Add [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) roles and labels where semantic HTML alone is insufficient |
+| **Color contrast** | Verify contrast ratios with [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) |
+| **Alt text** | Provide descriptive `alt` for meaningful images; use `alt=""` for decorative ones |
 
-### 🤔 Questions & Feedback
+Test your changes with Lighthouse or your browser's accessibility tools.
 
-Got questions or feedback? Join our [Discord community](https://discord.gg/5rJgQTnV4s), visit our [Reddit](https://www.reddit.com/r/OpenWebUI/), or open an issue. We're here to help!
-
-### 🚨 Reporting Issues
-
-Noticed something off? Have an idea? Check our [Issues tab](https://github.com/open-webui/open-webui/issues) to see if it's already been reported or suggested. If not, feel free to open a new issue. When reporting an issue, please follow our issue templates. These templates are designed to ensure that all necessary details are provided from the start, enabling us to address your concerns more efficiently.
-
-:::important
+---
 
-- **Template Compliance:** Please be aware that failure to follow the provided issue template, or not providing the requested information at all, will likely result in your issue being closed without further consideration. This approach is critical for maintaining the manageability and integrity of issue tracking.
+## Reporting Issues
 
-- **Detail is Key:** To ensure your issue is understood and can be effectively addressed, it's imperative to include comprehensive details. Descriptions should be clear, including steps to reproduce, expected outcomes, and actual results. Lack of sufficient detail may hinder our ability to resolve your issue.
+Check the [Issues tab](https://github.com/open-webui/open-webui/issues) before opening a new one. When filing:
 
-- **Respectful Communication:** All interactions — including issue reports and discussions — fall under our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. Hostile, entitled, or demanding behavior toward contributors will not be tolerated.
+- **Use the issue template.** Issues that do not follow the template or lack requested information will be closed.
+- **Include reproduction steps.** Describe what you did, what you expected, and what actually happened.
+- **Be specific.** Vague reports ("it doesn't work") cannot be investigated effectively.
 
+:::warning Scope of support
+Open WebUI supports Docker deployment, but we assume familiarity with Docker fundamentals. Issues related to reverse proxy configuration, container networking, or host OS setup are outside the project's support scope. Refer to the [official Docker documentation](https://docs.docker.com/get-started/overview/) for those topics.
 :::
 
-### 🧭 Scope of Support
-
-We've noticed an uptick in issues not directly related to Open WebUI but rather to the environment it's run in, especially Docker setups. While we strive to support Docker deployment, understanding Docker fundamentals is crucial for a smooth experience.
-
-- **Docker Deployment Support**: Open WebUI supports Docker deployment. Familiarity with Docker is assumed. For Docker basics, please refer to the [official Docker documentation](https://docs.docker.com/get-started/overview/).
-
-- **Advanced Configurations**: Setting up reverse proxies for HTTPS and managing Docker deployments requires foundational knowledge. There are numerous online resources available to learn these skills. Ensuring you have this knowledge will greatly enhance your experience with Open WebUI and similar projects.
-
-## 🙏 Thank You!
+---
 
-Your contributions, big or small, make a significant impact on Open WebUI. We're excited to see what you bring to the project!
+## Get in Touch
 
-Together, let's create an even more powerful tool for the community. 🌟
+| Channel | Link |
+|---------|------|
+| **Discord** | [discord.gg/5rJgQTnV4s](https://discord.gg/5rJgQTnV4s) |
+| **Reddit** | [r/OpenWebUI](https://www.reddit.com/r/OpenWebUI/) |
+| **GitHub Issues** | [open-webui/open-webui/issues](https://github.com/open-webui/open-webui/issues) |
+| **GitHub Discussions** | [open-webui/open-webui/discussions](https://github.com/open-webui/open-webui/discussions) |

docs/features/access-security/_category_.json → docs/features/administration/_category_.json

@@ -1,5 +1,5 @@
 {
-	"label": "🔐 Admin & Security",
+	"label": "🔧 Administration",
 	"position": 10,
 	"collapsible": true,
 	"collapsed": true

docs/features/access-security/analytics/index.mdx → docs/features/administration/analytics/index.mdx

@@ -54,7 +54,7 @@ Your selected time period is **automatically saved** and persists across browser
 
 ### Group Filtering
 
-If you have [user groups](/features/access-security/rbac/groups) configured, the Analytics dashboard allows filtering by group:
+If you have [user groups](/features/authentication-access/rbac/groups) configured, the Analytics dashboard allows filtering by group:
 
 - Use the **group dropdown** next to the time period selector
 - Select a specific group to view analytics **only for users in that group**
@@ -237,7 +237,7 @@ Example for GPT-4:
 - Compare **message counts** across models to see adoption rates
 - Check **token efficiency** (tokens per message) to identify verbose models
 - Monitor **trends** in the timeline chart after introducing new models
-- Combine with the [Evaluation feature](/features/access-security/evaluation/) for quality insights
+- Combine with the [Evaluation feature](/features/administration/evaluation/) for quality insights
 
 ### 3. Cost Management
 
@@ -408,6 +408,6 @@ Whether you're managing a personal instance or a large organizational deployment
 
 ## Related Features
 
-- [**Evaluation**](/features/access-security/evaluation/) - Measure model quality through user feedback
-- [**RBAC**](../rbac/index.mdx) - Control access to models and features per user
+- [**Evaluation**](/features/administration/evaluation/) - Measure model quality through user feedback
+- [**RBAC**](/features/authentication-access/rbac) - Control access to models and features per user
 - [**Data Controls**](/features/chat-conversations/data-controls/) - Manage chat history and exports

docs/features/administration/index.mdx

@@ -0,0 +1,72 @@
+---
+sidebar_position: 0
+title: "Administration"
+---
+
+# 🔧 Administration
+
+**Monitor usage, evaluate model quality, and communicate with your users, all from the Admin Panel.**
+
+Open WebUI gives administrators a full operational toolkit. Track which models your team uses and how much they cost. Run blind evaluations to find the best model for your workload. Push announcements to every user with customizable banners. Wire up webhooks to get notified when users sign up or when long-running tasks finish.
+
+---
+
+## What's In This Section
+
+| | |
+| :--- | :--- |
+| 📊 **[Analytics](./analytics)** | Usage dashboards with message volume, token consumption, model breakdowns, and per-user activity |
+| 🏆 **[Evaluation](./evaluation)** | Model arena, blind A/B testing, ELO-based leaderboards, and chat snapshots for fine-tuning |
+| 📢 **[Banners](./banners)** | Customizable system-wide announcements with dismissible notifications |
+| 🔔 **[Webhooks](./webhooks)** | Automated notifications for user sign-ups, chat completions, and external service integration |
+
+---
+
+## Analytics
+
+Get a bird's-eye view of how your instance is being used. The analytics dashboard shows message volume, token consumption, model popularity, and user activity, filterable by time period and user group.
+
+**Use it for:** capacity planning, cost estimation, identifying popular models, tracking adoption trends, and per-department usage reporting.
+
+[**Learn about Analytics →**](./analytics)
+
+---
+
+## Evaluation
+
+Not sure which model fits your team best? The evaluation system lets users rate model responses with thumbs up/down during normal conversations. Ratings feed into an ELO-based leaderboard, and rated chats are snapshotted for future model fine-tuning.
+
+**Two evaluation modes:**
+- **Arena Mode**: Randomly selects models for blind comparison, removing bias
+- **Normal interaction**: Rate responses during regular use, then compare models by swapping them out
+
+[**Learn about Evaluation →**](./evaluation)
+
+---
+
+## Banners
+
+Push high-visibility messages to every logged-in user. Use banners for maintenance windows, incident alerts, policy reminders, and feature announcements. Configure via the Admin Panel or the `WEBUI_BANNERS` environment variable for GitOps workflows.
+
+| Type | Color | Best for |
+|------|-------|----------|
+| `info` | Blue | General announcements |
+| `success` | Green | Resolved incidents, completed changes |
+| `warning` | Yellow | Planned maintenance, partial degradation |
+| `error` | Red | Active incidents, outages |
+
+[**Learn about Banners →**](./banners)
+
+---
+
+## Webhooks
+
+Three types of webhook integrations keep your external services in sync:
+
+| Webhook | Purpose |
+|---------|---------|
+| **Admin Webhook** | Notifies a Slack/Discord channel when a new user signs up |
+| **User Webhook** | Notifies individual users when a long-running chat response is ready |
+| **Channel Webhooks** | Let external services (CI/CD, monitoring, scripts) post messages into Open WebUI channels |
+
+[**Learn about Webhooks →**](./webhooks)