feat(i18n): full app + docs localization (de/en)
Build & Push Docker Image / build (push) Successful in 2m33s
Build & Push Docker Image / build (push) Successful in 2m33s
- translate remaining pages/components (admin, analytics, redundancy, trash, compare, browse, watchlist, admin tools tab, category combobox, theme toggle, tool preview card, tool-new/edit) to t() calls - locales: 453 keys each, parity verified - docs: bilingual handbook + release notes via *.en.md variants, language-aware docs.tsx (markdown paths, nav titles, search index), LanguageSwitcher in docs header - generate-docs: emit per-locale handbook/release/search output, localized index.json fields (fileEn/titleEn), en-aware snapshots
This commit is contained in:
opencode
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Administration
|
||||
order: 13
|
||||
---
|
||||
|
||||
# Administration
|
||||
|
||||
The **Admin** area (`/admin`) is exclusively accessible to admins.
|
||||
Without the admin role, access is denied.
|
||||
|
||||
> At the top right, the **Redundancy dashboard** button leads to the automatic
|
||||
> duplicate detection (see [Redundancy](/docs/handbook/redundanz)).
|
||||
|
||||
## "Users" tab
|
||||
|
||||
Management of local accounts.
|
||||
|
||||
- **Add user:** username (required), password (at least 6 characters),
|
||||
email (optional), **role** (User/Admin), **plan** (Free/Premium/Enterprise).
|
||||
- **Edit user:** set role, plan and (for local accounts) a new password.
|
||||
For OIDC accounts, password management is offered in the identity provider
|
||||
(e.g. Keycloak).
|
||||
- **Delete user:** permanently removes the account (not for your own account).
|
||||
|
||||
API reference:
|
||||
[`POST /users`](/docs/reference/endpoints/users#createUser),
|
||||
[`PATCH /users/{id}`](/docs/reference/endpoints/users#updateUser),
|
||||
[`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteUser).
|
||||
|
||||
## "Tools" tab
|
||||
|
||||
Central access to the tool catalog.
|
||||
|
||||
- **Search** for tools.
|
||||
- View, edit or move individual tools to the trash.
|
||||
- **Bulk action:** select multiple tools and move them to the trash
|
||||
(confirmation dialog; soft-deleted tools are removed from all public views
|
||||
and can be restored or permanently deleted).
|
||||
|
||||
## "Audit log" tab
|
||||
|
||||
Chronological log of all creation, change and deletion operations
|
||||
(max. 100 entries): action, entity + ID, timestamp, executing person and
|
||||
changed fields.
|
||||
|
||||
API reference: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs).
|
||||
|
||||
## "System" tab
|
||||
|
||||
Version information of the running instance:
|
||||
|
||||
- **Version** (e.g. `v0.8.1`),
|
||||
- **Commit** (7-digit SHA, linked to the repository),
|
||||
- **Build date**,
|
||||
- **Trash retention** ("N days" or "Forever").
|
||||
|
||||
## Tool links (Admin)
|
||||
|
||||
On the detail page of a tool you can manage **links** as an admin
|
||||
(own/"manual" as well as automatically detected ones):
|
||||
|
||||
- **Link tool:** dialog with tool ID, **relationship type**
|
||||
(Similar / Replaces / Superseded by) and optional notes.
|
||||
- Relationship types are displayed as badges on the detail page.
|
||||
- Manual links can be removed again via the trash icon.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Analytics
|
||||
order: 10
|
||||
---
|
||||
|
||||
# Analytics
|
||||
|
||||
The **Analytics** area (`/analytics`) is a public dashboard with
|
||||
metrics and charts based on all tools and ratings.
|
||||
|
||||
## Metrics (KPI cards)
|
||||
|
||||
- **Number of tools** — how many tools are recorded in the catalog.
|
||||
- **Number of ratings** — how many ratings were submitted in total.
|
||||
- **Active categories** — how many categories exist.
|
||||
- **Average rating** — global combined value.
|
||||
|
||||
## Charts
|
||||
|
||||
| Chart | Content |
|
||||
| --- | --- |
|
||||
| **Top 8 tools** | Bar chart of the tools with the highest combined score (0–5) |
|
||||
| **Tools per category** | Radar chart of the number of tools per category |
|
||||
| **Score distribution** | Two horizontal bar charts (usefulness & usability) per star |
|
||||
|
||||
The charts are interactive (tooltips on hover).
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getAnalyticsSummary)
|
||||
- [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#getTopTools)
|
||||
- [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getAnalyticsByCategory)
|
||||
- [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getRatingDistribution)
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Rating
|
||||
order: 7
|
||||
---
|
||||
|
||||
# Rating
|
||||
|
||||
On the detail page of a tool you can share your experience. Click on
|
||||
**Submit a rating** (requires an account).
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Usefulness** | Yes | 1–5 stars |
|
||||
| **Usability** | Yes | 1–5 stars |
|
||||
| **Comment** | No | Free text |
|
||||
| **Name** | No | Defaults to "Anonymous" |
|
||||
|
||||
Next to the fields, the **? icon** links directly to the associated field
|
||||
description in the [data model reference](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## What happens after submitting?
|
||||
|
||||
- Your rating is saved immediately and appears in the **rating list** of the
|
||||
detail page.
|
||||
- The **averages** (usefulness, usability, combined) and the **score
|
||||
distribution** are updated.
|
||||
- The **statistics** in the [Analytics](/docs/handbook/analytics) section are
|
||||
recalculated.
|
||||
|
||||
## Statistic sections on the detail page
|
||||
|
||||
- **Rating overview:** usefulness & usability as an average with progress
|
||||
bars.
|
||||
- **Score distribution:** number of ratings per star (1★–5★).
|
||||
- **History:** line chart of combined/individual values over time
|
||||
(only visible once there are several ratings).
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools/{id}/ratings`](/docs/reference/endpoints/ratings#createRating) — Submit a rating
|
||||
- [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listToolRatings) — Ratings of a tool
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Data model
|
||||
order: 17
|
||||
---
|
||||
|
||||
# Data model
|
||||
|
||||
This chapter explains the central data objects of toolr at the application
|
||||
level. The complete, automatically generated reference of all fields,
|
||||
types and constraints can be found in the
|
||||
[API reference](/docs/reference/schemas/tool).
|
||||
|
||||
## Tool
|
||||
|
||||
The heart of it all: a tool recorded in the catalog.
|
||||
|
||||
| Property | Description |
|
||||
| --- | --- |
|
||||
| `id` | Unique identifier |
|
||||
| `name` | Display name |
|
||||
| `description` | Description (what does the tool do?) |
|
||||
| `category` | Category assignment |
|
||||
| `websiteUrl` | Official website (optional) |
|
||||
| `iconUrl` | Logo/icon URL (optional) |
|
||||
| `features` | List of capabilities |
|
||||
| `tags` | List of keywords |
|
||||
| `createdAt` / `updatedAt` | Timestamps |
|
||||
| `createdBy` | Person who created it |
|
||||
| `deletedAt` / `deletedBy` | Soft deletion (trash) |
|
||||
|
||||
Input forms use the derived schemas
|
||||
[`ToolInput`](/docs/reference/schemas/toolinput) and
|
||||
[`ToolUpdate`](/docs/reference/schemas/toolupdate).
|
||||
Aggregated views are provided by [`ToolWithStats`](/docs/reference/schemas/toolwithstats)
|
||||
(e.g. with average rating).
|
||||
|
||||
## Rating (Bewertung)
|
||||
|
||||
A single rating for a tool:
|
||||
|
||||
- `usefulness` (Nützlichkeit, 1–5) and `usability` (Bedienbarkeit, 1–5)
|
||||
- optional `comment` and a display name (`reviewerName`)
|
||||
- timestamp
|
||||
|
||||
Input schema: [`RatingInput`](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## User & Auth
|
||||
|
||||
- [`User`](/docs/reference/schemas/user) — user account with role (User/Admin)
|
||||
and plan (Free/Premium/Enterprise).
|
||||
- [`AuthUser`](/docs/reference/schemas/authuser) — the logged-in profile
|
||||
including `entitlements` (available features).
|
||||
- [`UserPreferences`](/docs/reference/schemas/userpreferences) — view and
|
||||
density preferences as well as the `watchlist` (list of tool IDs).
|
||||
|
||||
## Analytics
|
||||
|
||||
The statistics endpoints provide aggregated data:
|
||||
|
||||
- [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary) — global
|
||||
metrics (number of tools/ratings, categories, average).
|
||||
- [`TopToolEntry`](/docs/reference/schemas/TopToolEntry) — an entry of the
|
||||
top tools.- [`CategoryStats`](/docs/reference/schemas/categorystats) — number of tools per
|
||||
category.
|
||||
- [`RatingDistribution`](/docs/reference/schemas/ratingdistribution) —
|
||||
score distribution (usefulness & usability).
|
||||
- [`ScoreBucket`](/docs/reference/schemas/scorebucket) — a value bucket.
|
||||
|
||||
## Additional
|
||||
|
||||
- [`VersionInfo`](/docs/reference/schemas/versioninfo) — version, commit SHA,
|
||||
build date and trash retention of the running instance.
|
||||
- [`AuditLog`](/docs/reference/schemas/auditlog) — a log entry
|
||||
(action, entity, timestamp, actor, changes).
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Getting Started
|
||||
order: 2
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
This page guides you through the most important workflows in toolr — from your
|
||||
first visit to creating and rating a tool.
|
||||
|
||||
## 1. Sign in
|
||||
|
||||
Most actions (create a tool, rate, watchlist, compare) require
|
||||
an account. Click **Sign in** in the bottom left corner. Depending on the
|
||||
instance configuration you have two options:
|
||||
|
||||
- **Local accounts:** username + password. Access is created by an admin
|
||||
(see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** sign in with the configured identity provider (e.g.
|
||||
Keycloak).
|
||||
|
||||
Which mode is active is shown by the
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode) endpoint. Details
|
||||
can be found in the [Sign in & account](/docs/handbook/konto) section.
|
||||
|
||||
## 2. Find tools
|
||||
|
||||
Open the **Browse tools** section:
|
||||
|
||||
- **Search** — full-text search across name & description (shortcut `/`).
|
||||
- **Filter** — by category, tags, features and minimum rating
|
||||
(`minRating`).
|
||||
- **Sort** — by newest, top-rated, most rated, name
|
||||
(ascending/descending) or last update.
|
||||
|
||||
All options in detail: [Find & browse tools](/docs/handbook/tools-finden).
|
||||
|
||||
## 3. Create a tool
|
||||
|
||||
Go to **Add tool** and fill in the form. Details for each field can be found
|
||||
in the [Create a tool](/docs/handbook/tool-anlegen) section and in the
|
||||
[field reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
## 4. Rate
|
||||
|
||||
On the detail page of a tool you can submit **usefulness** and **usability**
|
||||
(1–5 each) and optionally leave a comment. Your
|
||||
rating is immediately reflected in the statistics.
|
||||
See [Rating](/docs/handbook/bewerten).
|
||||
|
||||
## 5. Further reading
|
||||
|
||||
- [Compare tools](/docs/handbook/vergleichen)
|
||||
- [Watchlist](/docs/handbook/watchlist)
|
||||
- [Analytics](/docs/handbook/analytics)
|
||||
- [Plans & permissions](/docs/handbook/plaene)
|
||||
- [Administration](/docs/handbook/administration)
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Overview
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Welcome to toolr
|
||||
|
||||
toolr is a platform for **discovering, rating and comparing development
|
||||
tools**. Users maintain a shared catalog of tools, submit ratings
|
||||
(usefulness & usability) and use statistics to make the right choice.
|
||||
|
||||
## What can you do with toolr?
|
||||
|
||||
| Function | Description | Visibility |
|
||||
| --- | --- | --- |
|
||||
| **Browse tools** | Filter, sort and search the catalog | Everyone |
|
||||
| **Create a tool** | Add a new tool with description, category, features & tags | Logged in |
|
||||
| **Edit/delete tools** | Maintain your own tools (creator or admin) | Logged in |
|
||||
| **Rate** | Submit usefulness & usability (1–5) plus a comment | Logged in |
|
||||
| **Watchlist** | Save tools as favorites | Premium |
|
||||
| **Compare** | View tools side by side | Premium |
|
||||
| **Record costs** | Enter license and cost models per tool | Premium |
|
||||
| **Analytics** | Statistics, top tools, distributions | Everyone |
|
||||
| **Trash** | Restore soft-deleted tools or delete them permanently | Premium |
|
||||
| **Admin** | User management, audit log, system information | Admin |
|
||||
| **Redundancy detection** | Automatic duplicate detection | Admin |
|
||||
|
||||
## How this documentation is organized
|
||||
|
||||
- **User Guide** (these pages): step-by-step instructions for all
|
||||
functions — from the [Getting Started](/docs/handbook/getting-started) to
|
||||
[Administration](/docs/handbook/administration).
|
||||
- **API Reference**: automatically generated from the OpenAPI specification —
|
||||
all [endpoints](/docs/reference/endpoints/tools) and
|
||||
[data fields](/docs/reference/schemas/toolinput) of the current version.
|
||||
- **Release Notes**: what is new in each [version](/docs/releases/v0.8.1).
|
||||
|
||||
## Getting started
|
||||
|
||||
The fastest way:
|
||||
|
||||
1. **Sign in** — without an account you can only browse
|
||||
(see [Getting Started](/docs/handbook/getting-started#1-anmelden)).
|
||||
2. **Find tools** — search, filters and sorting in the
|
||||
[Browse tools](/docs/handbook/tools-finden) section.
|
||||
3. **Create a tool** — via "Add tool"
|
||||
([guide](/docs/handbook/tool-anlegen)).
|
||||
4. **Rate** — on the detail page of a tool
|
||||
([guide](/docs/handbook/bewerten)).
|
||||
|
||||
## Contact & source code
|
||||
|
||||
The source code is available at
|
||||
[git.kubebase.de/admin/tool-evaluator](https://git.kubebase.de/admin/tool-evaluator) —
|
||||
you can reach it at any time via the repository icon in the top right corner.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Login & Account
|
||||
order: 3
|
||||
---
|
||||
|
||||
# Login & Account
|
||||
|
||||
## Logging in
|
||||
|
||||
Click **Login** at the bottom left of the sidebar. Depending on the
|
||||
configuration of the instance:
|
||||
|
||||
- **Local accounts:** enter username and password. The accounts are created
|
||||
by an admin (see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** you are redirected to the configured identity provider and
|
||||
log in there.
|
||||
|
||||
The active mode is available at the endpoint
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode).
|
||||
|
||||
> You can reach the login page directly at `/login`. After a successful
|
||||
> login you are redirected back to the page you originally requested.
|
||||
|
||||
## User profile
|
||||
|
||||
You can see your profile (avatar, name, email, plan) at the bottom left in
|
||||
the user menu. There you have the following actions available:
|
||||
|
||||
- **Watchlist** — your saved tools (only with the corresponding plan).
|
||||
- **Trash** — restorable, deleted tools (Premium/Enterprise).
|
||||
- **Change password** — directly in toolr for local accounts; for OIDC
|
||||
accounts, password management is offered in the identity provider.
|
||||
- **Logout** — ends your session.
|
||||
|
||||
## Changing your password (local account)
|
||||
|
||||
1. Open the user menu at the bottom left.
|
||||
2. Select **Change password**.
|
||||
3. Enter the **current** and a **new** password (min. 6 characters) and
|
||||
confirm it.
|
||||
4. Save — the password takes effect immediately.
|
||||
|
||||
API reference: [`POST /auth/me/password`](/docs/reference/endpoints/auth#changeMyPassword).
|
||||
|
||||
## Display settings
|
||||
|
||||
Using the buttons at the top right you can:
|
||||
|
||||
- switch the **language** (German / English),
|
||||
- toggle the **theme** (Light / Dark / System),
|
||||
- adjust the **list view** and **density** in the Browse tools section
|
||||
(see [Finding & browsing tools](/docs/handbook/tools-finden)).
|
||||
|
||||
Your preferences (incl. watchlist) are saved at the endpoint
|
||||
[`GET /auth/me/preferences`](/docs/reference/endpoints/auth#getMePreferences)
|
||||
and updated via [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updateMePreferences).
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Recording Costs
|
||||
order: 12
|
||||
---
|
||||
|
||||
# Recording Costs
|
||||
|
||||
On the detail page of a tool you can enter cost and license models so that
|
||||
the total costs per tool become transparent.
|
||||
|
||||
> Costs is a **premium feature** (`costs`, Premium/Enterprise). Admins always
|
||||
> have access.
|
||||
|
||||
## Adding costs
|
||||
|
||||
Click **Add costs** in the costs section of the detail page and fill out the
|
||||
form:
|
||||
|
||||
| Field | Notes |
|
||||
| --- | --- |
|
||||
| **License type** | Free / Subscription / One-Time / Usage-Based |
|
||||
| **Billing period** | Only for "Subscription": Monthly / Quarterly / Annually |
|
||||
| **Costs** | Amount as a number |
|
||||
| **Currency** | EUR / USD / GBP / CHF |
|
||||
| **Notes** | Optional free text |
|
||||
|
||||
Saving creates the entry. Each cost entry is displayed as a card with
|
||||
license badge, billing period, amount (`Amount Currency` or "Free") and
|
||||
notes.
|
||||
|
||||
## Editing & deleting costs
|
||||
|
||||
Hovering over a cost card shows the **Edit** (pencil) and **Delete** (trash)
|
||||
actions.
|
||||
|
||||
## API
|
||||
|
||||
The cost data is managed via the tool endpoints
|
||||
(see [API reference](/docs/reference/endpoints/tools)).
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Trash
|
||||
order: 15
|
||||
---
|
||||
|
||||
# Trash
|
||||
|
||||
The **trash** (`/trash`) contains soft-deleted tools. With trash access
|
||||
they can be restored; permanent deletion is reserved for admins.
|
||||
|
||||
> The trash is a **premium feature** (`trash`, Premium/Enterprise).
|
||||
> Admins always have access.
|
||||
|
||||
## Access
|
||||
|
||||
The trash can be reached via the user menu or the sidebar.
|
||||
Without the `trash` permission, a hint about changing the plan appears.
|
||||
|
||||
## Restoring
|
||||
|
||||
- Select one or more tools (checkboxes).
|
||||
- Click on **Restore (N)** — the tools appear again in all
|
||||
public views.
|
||||
|
||||
> Restoring is available to anyone with trash access.
|
||||
|
||||
## Permanently delete (admin only)
|
||||
|
||||
- **Delete (N)** **permanently** removes the selected tools — including
|
||||
all ratings, costs and links. This cannot be undone.
|
||||
- **Empty trash** permanently removes all soft-deleted tools.
|
||||
|
||||
## Table
|
||||
|
||||
The trash lists: name, category, **Deleted on** (`tt.MM.jjjj HH:mm`),
|
||||
**Deleted by** as well as actions (Restore; Delete admin only). The search
|
||||
filters by name.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /tools/trash`](/docs/reference/endpoints/tools#listTrashedTools) — list
|
||||
- [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoreTools) — restore
|
||||
- [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deleteTrashedTools) — permanently delete (admin)
|
||||
- [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptyTrash) — empty trash (admin)
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Plans & Permissions
|
||||
order: 11
|
||||
---
|
||||
|
||||
# Plans & Permissions
|
||||
|
||||
toolr distinguishes **plans** (tier) and **roles**. Admins bypass all feature
|
||||
restrictions.
|
||||
|
||||
## Plans
|
||||
|
||||
| Plan | Description |
|
||||
| --- | --- |
|
||||
| **Free** | Basic functions: search, filter, view, analytics |
|
||||
| **Premium** | Additionally watchlist, compare, trash, costs |
|
||||
| **Enterprise** | All premium features + extended support |
|
||||
|
||||
### Feature permissions
|
||||
|
||||
Premium/Enterprise unlock the following features:
|
||||
|
||||
| Feature | Function | Learn more |
|
||||
| --- | --- | --- |
|
||||
| `compare` | Compare tools | [Compare](/docs/handbook/vergleichen) |
|
||||
| `watchlist` | Favorites list | [Watchlist](/docs/handbook/watchlist) |
|
||||
| `trash` | Trash (soft-deleted tools) | [Trash](/docs/handbook/papierkorb) |
|
||||
| `costs` | Record cost/license models | [Recording costs](/docs/handbook/kosten) |
|
||||
|
||||
If you are missing a feature, the app shows an **upgrade notice** with a link
|
||||
to the plan management.
|
||||
|
||||
## Roles
|
||||
|
||||
| Role | Permissions |
|
||||
| --- | --- |
|
||||
| **User** | Standard account: create/rate tools, edit your own tools |
|
||||
| **Admin** | All user rights + administration, audit log, redundancy, empty trash, tool links |
|
||||
|
||||
Admins pass **all** feature checks — even without a premium plan.
|
||||
|
||||
## Plan/role management
|
||||
|
||||
The assignment of role and plan is managed by admins in the
|
||||
[Administration](/docs/handbook/administration) section (tab "Users").
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Redundancy dashboard
|
||||
order: 14
|
||||
---
|
||||
|
||||
# Redundancy dashboard
|
||||
|
||||
The **Redundancy dashboard** (`/admin/redundancy`) is an admin tool for
|
||||
automatic detection of duplicate or strongly overlapping tools — per
|
||||
category — including cost and rating comparison.
|
||||
|
||||
> Access is reserved exclusively for admins (the API is
|
||||
> admin-protected).
|
||||
|
||||
## Layout
|
||||
|
||||
- **Per category** a group is shown: name of the category,
|
||||
number of tools and comparisons as well as the **total monthly costs**
|
||||
if applicable (e.g. `€X.XX/mo total`).
|
||||
- Each tool is displayed as a card: name, monthly costs, number of
|
||||
ratings, combined rating, license badges and number of features.
|
||||
|
||||
## Comparisons & recommendations
|
||||
|
||||
For each tool pair the following appears:
|
||||
|
||||
- Tool A vs. Tool B, each with rating (`X.X ★`) and monthly costs.
|
||||
- **Overlap** in percent (progress bar in the middle).
|
||||
- A **recommendation** with confidence color:
|
||||
- **high** (green), **medium** (yellow), **low** (gray)
|
||||
- The recommended, better tool is marked with a "thumbs up" and justified.
|
||||
|
||||
## Manual rating
|
||||
|
||||
You can rate a pair manually: click on Tool A or Tool B to
|
||||
record which one is better. The selection is saved and the
|
||||
display is updated.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /api/admin/redundancy`](#) — load data (admin-protected)
|
||||
- [`POST /api/admin/redundancy/evaluate`](#) — save manual rating
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Keyboard shortcuts & command palette
|
||||
order: 16
|
||||
---
|
||||
|
||||
# Keyboard shortcuts & command palette
|
||||
|
||||
## Command palette
|
||||
|
||||
The command palette is the central quick navigation:
|
||||
|
||||
- Open with **`⌘K`** (macOS) or **`Ctrl+K`** (Windows/Linux).
|
||||
- Alternatively via the search bar at the top right ("Search tools… ⌘K") or the
|
||||
search icon on mobile devices.
|
||||
|
||||
### Empty state
|
||||
|
||||
Without input, the palette shows:
|
||||
|
||||
- **Recently viewed** — the last 5 tools you visited.
|
||||
- **Navigation** — browse tools, add tool, analytics as well as
|
||||
(depending on permissions) watchlist, trash and admin.
|
||||
|
||||
### Search
|
||||
|
||||
Type to search for tools live (max. 10 results, incl. rating
|
||||
`X.X★`).
|
||||
|
||||
## Overview of keyboard shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| `⌘K` / `Ctrl+K` | Open command palette |
|
||||
| `/` | Focus search in the "Browse tools" area |
|
||||
|
||||
## Additional notes
|
||||
|
||||
- **Recently viewed** is stored locally in the browser (max. 5 entries).
|
||||
- The sidebar (left navigation) can be collapsed on desktop; the
|
||||
breadcrumb at the top shows your current location.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Create a tool
|
||||
order: 5
|
||||
---
|
||||
|
||||
# Create a tool
|
||||
|
||||
To add a new tool to the catalog, click **Add tool**
|
||||
(`/tools/new`). Creating a tool requires an account — without being signed in
|
||||
a notice with a login button appears.
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Name** | Yes | At least 2 characters |
|
||||
| **Category** | Yes | Dropdown; new categories can be created directly |
|
||||
| **Website URL** | No | Valid URL (e.g. `https://...`) |
|
||||
| **Icon / Logo URL** | No | Valid URL; preview is shown live |
|
||||
| **Description** | Yes | At least 10 characters; describe what the tool does |
|
||||
| **Features** | No | Dynamic list with autocomplete (max. 6) |
|
||||
| **Tags** | No | Dynamic list with autocomplete |
|
||||
|
||||
Next to each field, the **? icon** takes you directly to the corresponding
|
||||
field description in the [data model reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
### Category
|
||||
|
||||
- Type to search for existing categories.
|
||||
- Select **+ Create "..."** to create a new category.
|
||||
|
||||
### Features & tags
|
||||
|
||||
- **Add feature** / **Add tag** appends a new row.
|
||||
- The input fields suggest existing features/tags
|
||||
(autocomplete, max. 6 suggestions).
|
||||
- Use the **×** button to remove individual rows.
|
||||
- Features and tags help with filtering and finding tools again.
|
||||
|
||||
## Save
|
||||
|
||||
Click **Add tool**. After successful creation you will be redirected to the
|
||||
detail page of the new tool.
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools`](/docs/reference/endpoints/tools#createTool) — create a tool
|
||||
- [`GET /categories`](/docs/reference/endpoints/tools#listCategories) — categories
|
||||
- [`GET /features/all`](/docs/reference/endpoints/tools#listAllFeatures) — features
|
||||
- [`GET /tags/all`](/docs/reference/endpoints/tools#listAllTags) — tags
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Edit & delete tools
|
||||
order: 6
|
||||
---
|
||||
|
||||
# Edit & delete tools
|
||||
|
||||
## Editing
|
||||
|
||||
On the detail page of a tool you will find the **Edit** button
|
||||
(only for the person who created the tool, as well as for admins).
|
||||
|
||||
The edit page (`/tools/:id/edit`) contains the same fields as when
|
||||
creating (name, category, website/icon URL, description, features, tags) —
|
||||
already filled with the current values.
|
||||
|
||||
- **Save** applies the changes.
|
||||
- **Cancel** takes you back to the detail page.
|
||||
|
||||
API reference: [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updateTool).
|
||||
|
||||
## Deleting
|
||||
|
||||
Via **Delete** on the detail page the tool is removed. The behavior
|
||||
depends on your plan:
|
||||
|
||||
- **With trash access** (Premium/Enterprise or Admin): the tool is
|
||||
**soft deleted** — it disappears from all public views, but can
|
||||
be restored or permanently deleted in the [trash](/docs/handbook/papierkorb).
|
||||
- **Without trash access:** the tool is **permanently** deleted and cannot
|
||||
be restored.
|
||||
|
||||
Deletion is only possible for the person who created the tool, as well as
|
||||
for admins.
|
||||
|
||||
API reference: [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deleteTool).
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Find & browse tools
|
||||
order: 4
|
||||
---
|
||||
|
||||
# Find & browse tools
|
||||
|
||||
The **Browse tools** section (`/tools`) is your entry point to the catalog.
|
||||
Here you combine search, filters and sorting to find exactly the tools
|
||||
you are interested in.
|
||||
|
||||
## Search
|
||||
|
||||
- The **search bar** searches name and description (full text).
|
||||
- Shortcut: Press **`/`** to focus the search.
|
||||
- The input is debounced so that filtering happens immediately with each
|
||||
keystroke.
|
||||
|
||||
## Filter
|
||||
|
||||
Via the **Filter** button (with a badge for the number of active filters)
|
||||
you open the filter popover with:
|
||||
|
||||
- **Tags** — selection via checkboxes (scrollable list).
|
||||
- **Features** — selection via checkboxes.
|
||||
- **Minimum rating** — slider from 0 to 5 (in steps of 0.5); shows
|
||||
e.g. "3.0+".
|
||||
|
||||
Active filters appear as **removable chips** above the result list.
|
||||
Use **Reset filters** or **Remove all** to clear them again.
|
||||
|
||||
## Sort
|
||||
|
||||
The **Sort** dropdown offers the following options:
|
||||
|
||||
| Sort | Description |
|
||||
| --- | --- |
|
||||
| Newest | New tools first |
|
||||
| Top rated | By combined rating |
|
||||
| Most rated | By number of ratings |
|
||||
| Name (A–Z) | Alphabetically ascending |
|
||||
| Name (Z–A) | Alphabetically descending |
|
||||
| Last updated | By last update |
|
||||
|
||||
## View & density
|
||||
|
||||
- **Switch view:** grid / table / rows.
|
||||
- **Density:** comfortable / compact (slider).
|
||||
|
||||
Your selection is saved — locally in the browser and, for logged-in users,
|
||||
additionally on the server in the preferences. View, density, search, filters
|
||||
and sorting are reflected in the URL so you can share results.
|
||||
|
||||
## Table view
|
||||
|
||||
In the table view the columns **Tool**, **Rating** and **Number of
|
||||
ratings** are sortable. Hovering over a row shows a preview
|
||||
with rating details, tags and mini bars.
|
||||
|
||||
## Selecting for comparison & watchlist
|
||||
|
||||
- On every card/row you find a **compare icon** that lets you add tools to the
|
||||
[compare bar](/docs/handbook/vergleichen).
|
||||
- The **bookmark icon** saves tools to your
|
||||
[watchlist](/docs/handbook/watchlist) (only with the corresponding plan).
|
||||
|
||||
## API
|
||||
|
||||
All search, filter and sort parameters correspond to the query parameters of
|
||||
[`GET /tools`](/docs/reference/endpoints/tools#listTools).
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Compare
|
||||
order: 9
|
||||
---
|
||||
|
||||
# Compare
|
||||
|
||||
With the compare function you can put several tools **side by side** —
|
||||
ideal for making a well-informed decision.
|
||||
|
||||
> Comparing is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Selecting tools
|
||||
|
||||
1. In the **Browse tools** section, click the **compare icon** (scales) on
|
||||
each card/row.
|
||||
2. The **compare bar** appears at the bottom with the selected tools as
|
||||
chips. You can remove individual tools (×) or clear the selection.
|
||||
3. Click **Compare (N)** to go to the compare view.
|
||||
|
||||
> Without a premium plan the button is locked (lock icon). The dialog takes
|
||||
> you to the plan switch
|
||||
> (see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## The compare view
|
||||
|
||||
The view shows a table with one column per tool. Rows:
|
||||
|
||||
| Row | Content |
|
||||
| --- | --- |
|
||||
| **Rating** | Stars + value (e.g. `4.2/5`) |
|
||||
| **Usefulness** | Value (X.X/5) |
|
||||
| **Usability** | Value (X.X/5) |
|
||||
| **Number of ratings** | Count |
|
||||
| **Description** | Text |
|
||||
| **Features** | Badges |
|
||||
| **Tags** | Badges |
|
||||
| **Last updated** | Date |
|
||||
|
||||
The **best value** per row is highlighted (with trophy icon).
|
||||
|
||||
## API
|
||||
|
||||
The compare view reads the data via
|
||||
[`GET /compare`](/docs/reference/endpoints/tools#listCompareTools).
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Watchlist
|
||||
order: 8
|
||||
---
|
||||
|
||||
# Watchlist
|
||||
|
||||
The **watchlist** is a personal favorites list. You can open and compare the
|
||||
tools in it at any time with a click.
|
||||
|
||||
> The watchlist is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Prerequisite
|
||||
|
||||
You need a plan with the `watchlist` permission. If it is missing, a note
|
||||
about switching plans appears at the bookmark
|
||||
(see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## Saving a tool
|
||||
|
||||
- On every card/row in the **Browse tools** section you will find the
|
||||
**bookmark icon**.
|
||||
- A click saves the tool to your watchlist — the icon becomes filled.
|
||||
- Clicking it again removes it.
|
||||
|
||||
## Viewing the watchlist
|
||||
|
||||
Open the watchlist via the user menu or the sidebar. It shows all saved tools
|
||||
as cards. The filled bookmark on a card removes the tool from the list.
|
||||
|
||||
## Where is the watchlist stored?
|
||||
|
||||
The watchlist is a list of tool IDs in your **user preferences**. This way it
|
||||
is linked to your account across devices.
|
||||
|
||||
API reference: [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getMeWatchlist).
|
||||
@@ -0,0 +1,37 @@
|
||||
# v0.6.0 — Release Notes
|
||||
|
||||
**Date:** 2026-08-03 · **Tag:** [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.6.0)
|
||||
|
||||
## New features
|
||||
|
||||
- Complete modernization of all dependencies to the current major versions
|
||||
(TypeScript 7, Vite 8, React 19.2, openid-client 6, zod 4, recharts 3, react-day-picker 10).
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- CI build fixed via `allowBuilds` configuration for pnpm 11
|
||||
(build scripts for esbuild & Co. are no longer blocked).
|
||||
- Image tagging simplified: only `latest` and `v*` tags, no more `nightly-*`/`sha-*` tags.
|
||||
- All dependencies pinned exactly; automatic updates via Renovate prepared
|
||||
(`renovate.json`, `docs/dependency-policy.md`).
|
||||
|
||||
## API changes
|
||||
|
||||
- No breaking changes to the API. openid-client internally migrated to v6
|
||||
(auth flow behaves identically).
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged. Node image pinned to `node:24.18.1-alpine`.
|
||||
- **Migration:** no database migration required.
|
||||
- **Breaking changes:** none.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- `typedoc` (indirect orval dependency) shows a peer-dependency warning
|
||||
(expects TypeScript 5.x/6.x, 7.x is installed) — harmless for build and runtime.
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`2f66fff`](https://git.kubebase.de/admin/tool-evaluator/commit/2f66fff)
|
||||
- Tag: [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.6.0)
|
||||
@@ -0,0 +1,35 @@
|
||||
# v0.7.0 — Release Notes
|
||||
|
||||
**Date:** 2026-08-03 · **Tag:** [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.7.0)
|
||||
|
||||
## New features
|
||||
|
||||
- Version-bound **release documentation** in the app under `/docs`
|
||||
(index + detail page per version, Markdown from `docs/releases/`).
|
||||
- Generated release template (`docs/releases/TEMPLATE.md`) and
|
||||
sync step for the frontend build.
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- `tsx` bumped to 4.23.4 — last outdated dependency in the workspace
|
||||
(`pnpm outdated -r` is now empty).
|
||||
|
||||
## API changes
|
||||
|
||||
- No breaking changes to the API.
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged.
|
||||
- **Migration:** none.
|
||||
- **Breaking changes:** none.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- The documentation is currently limited to release notes; a complete
|
||||
API/field reference will follow in v0.8.0.
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`520f917`](https://git.kubebase.de/admin/tool-evaluator/commit/520f917)
|
||||
- Tag: [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.7.0)
|
||||
@@ -0,0 +1,46 @@
|
||||
# v0.8.0 — Release Notes
|
||||
|
||||
**Date:** 2026-08-03 · **Tag:** [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.0)
|
||||
|
||||
## New features
|
||||
|
||||
- **Complete documentation site** in mkdocs look under `/docs`:
|
||||
- **Manual** with understandable explanations of all features
|
||||
(Getting started, creating a tool, evaluations, comparing, watchlist,
|
||||
analytics, administration, data model).
|
||||
- **Automatically generated reference** from `lib/api-spec/openapi.yaml`:
|
||||
all endpoints and data fields (type, required status, constraints) —
|
||||
this guarantees that *every* feature is documented.
|
||||
- **Search** across the manual, endpoints, and fields.
|
||||
- **Version dropdown**: older releases keep their full field/endpoint
|
||||
reference as a snapshot.
|
||||
- **Repo link** to the source in the top right.
|
||||
- **Help buttons (?) in forms** (NetBox style): next to each field,
|
||||
an icon jumps directly to the field description in the docs.
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- Docs generator `scripts/src/generate-docs.mjs` replaces the previous
|
||||
`sync-release-docs.mjs` (OpenAPI parsing, manual, search index, snapshots).
|
||||
- Documentation for v0.7.0 backfilled.
|
||||
|
||||
## API changes
|
||||
|
||||
- No breaking changes to the API.
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged.
|
||||
- **Migration:** none.
|
||||
- **Breaking changes:** none.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- Manual & reference apply to the current version; older versions
|
||||
show their release notes and a reference snapshot, if generated at
|
||||
release time (`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`).
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`6c92b63`](https://git.kubebase.de/admin/tool-evaluator/commit/6c92b63)
|
||||
- Tag: [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.0)
|
||||
@@ -0,0 +1,47 @@
|
||||
# v0.8.1 — Release Notes
|
||||
|
||||
**Date:** 2026-08-03 · **Tag:** [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.1)
|
||||
|
||||
## New features
|
||||
|
||||
- **Standalone docs page**: The documentation is now available as its own,
|
||||
mkdocs-like page at `toolr.kubebase.de/docs` — without the app shell
|
||||
(own header with repo link, version dropdown, search, theme toggle
|
||||
and link back to the app).
|
||||
- **Navigation renamed**: The sidebar entry is now called **"Help"**
|
||||
and leads to the standalone docs.
|
||||
- **User guide completely revised**: 17 manual pages with
|
||||
step-by-step instructions for all features (finding tools, creating a
|
||||
tool, evaluating, watchlist, comparing, costs, analytics, plans,
|
||||
administration, redundancy, trash, keyboard shortcuts, data model).
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- Reference links are now case-insensitive
|
||||
(schema/endpoint slugs such as `toolinput` and `ToolInput` both work).
|
||||
- Manual links to endpoint anchors corrected (PascalCase operation IDs).
|
||||
- Outdated, broken manual links (`vergleichen`, `watchlist` …) replaced.
|
||||
- Documentation table headers and notice texts in the docs page
|
||||
internationalized via i18n (de/en).
|
||||
|
||||
## API changes
|
||||
|
||||
- No changes to the API.
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged.
|
||||
- **Migration:** none.
|
||||
- **Breaking changes:** none. The docs page is reachable under `/docs` as
|
||||
before; only the presentation is now standalone.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- Manual & reference apply to the current version; older versions show
|
||||
their release notes and a reference snapshot, if generated at release time
|
||||
(`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`).
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`fdf2d74`](https://git.kubebase.de/admin/tool-evaluator/commit/fdf2d74)
|
||||
- Tag: [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.1)
|
||||
@@ -0,0 +1,61 @@
|
||||
|
||||
# Administration
|
||||
|
||||
The **Admin** area (`/admin`) is exclusively accessible to admins.
|
||||
Without the admin role, access is denied.
|
||||
|
||||
> At the top right, the **Redundancy dashboard** button leads to the automatic
|
||||
> duplicate detection (see [Redundancy](/docs/handbook/redundanz)).
|
||||
|
||||
## "Users" tab
|
||||
|
||||
Management of local accounts.
|
||||
|
||||
- **Add user:** username (required), password (at least 6 characters),
|
||||
email (optional), **role** (User/Admin), **plan** (Free/Premium/Enterprise).
|
||||
- **Edit user:** set role, plan and (for local accounts) a new password.
|
||||
For OIDC accounts, password management is offered in the identity provider
|
||||
(e.g. Keycloak).
|
||||
- **Delete user:** permanently removes the account (not for your own account).
|
||||
|
||||
API reference:
|
||||
[`POST /users`](/docs/reference/endpoints/users#createUser),
|
||||
[`PATCH /users/{id}`](/docs/reference/endpoints/users#updateUser),
|
||||
[`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteUser).
|
||||
|
||||
## "Tools" tab
|
||||
|
||||
Central access to the tool catalog.
|
||||
|
||||
- **Search** for tools.
|
||||
- View, edit or move individual tools to the trash.
|
||||
- **Bulk action:** select multiple tools and move them to the trash
|
||||
(confirmation dialog; soft-deleted tools are removed from all public views
|
||||
and can be restored or permanently deleted).
|
||||
|
||||
## "Audit log" tab
|
||||
|
||||
Chronological log of all creation, change and deletion operations
|
||||
(max. 100 entries): action, entity + ID, timestamp, executing person and
|
||||
changed fields.
|
||||
|
||||
API reference: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs).
|
||||
|
||||
## "System" tab
|
||||
|
||||
Version information of the running instance:
|
||||
|
||||
- **Version** (e.g. `v0.8.1`),
|
||||
- **Commit** (7-digit SHA, linked to the repository),
|
||||
- **Build date**,
|
||||
- **Trash retention** ("N days" or "Forever").
|
||||
|
||||
## Tool links (Admin)
|
||||
|
||||
On the detail page of a tool you can manage **links** as an admin
|
||||
(own/"manual" as well as automatically detected ones):
|
||||
|
||||
- **Link tool:** dialog with tool ID, **relationship type**
|
||||
(Similar / Replaces / Superseded by) and optional notes.
|
||||
- Relationship types are displayed as badges on the detail page.
|
||||
- Manual links can be removed again via the trash icon.
|
||||
@@ -0,0 +1,29 @@
|
||||
|
||||
# Analytics
|
||||
|
||||
The **Analytics** area (`/analytics`) is a public dashboard with
|
||||
metrics and charts based on all tools and ratings.
|
||||
|
||||
## Metrics (KPI cards)
|
||||
|
||||
- **Number of tools** — how many tools are recorded in the catalog.
|
||||
- **Number of ratings** — how many ratings were submitted in total.
|
||||
- **Active categories** — how many categories exist.
|
||||
- **Average rating** — global combined value.
|
||||
|
||||
## Charts
|
||||
|
||||
| Chart | Content |
|
||||
| --- | --- |
|
||||
| **Top 8 tools** | Bar chart of the tools with the highest combined score (0–5) |
|
||||
| **Tools per category** | Radar chart of the number of tools per category |
|
||||
| **Score distribution** | Two horizontal bar charts (usefulness & usability) per star |
|
||||
|
||||
The charts are interactive (tooltips on hover).
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getAnalyticsSummary)
|
||||
- [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#getTopTools)
|
||||
- [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getAnalyticsByCategory)
|
||||
- [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getRatingDistribution)
|
||||
@@ -0,0 +1,39 @@
|
||||
|
||||
# Rating
|
||||
|
||||
On the detail page of a tool you can share your experience. Click on
|
||||
**Submit a rating** (requires an account).
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Usefulness** | Yes | 1–5 stars |
|
||||
| **Usability** | Yes | 1–5 stars |
|
||||
| **Comment** | No | Free text |
|
||||
| **Name** | No | Defaults to "Anonymous" |
|
||||
|
||||
Next to the fields, the **? icon** links directly to the associated field
|
||||
description in the [data model reference](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## What happens after submitting?
|
||||
|
||||
- Your rating is saved immediately and appears in the **rating list** of the
|
||||
detail page.
|
||||
- The **averages** (usefulness, usability, combined) and the **score
|
||||
distribution** are updated.
|
||||
- The **statistics** in the [Analytics](/docs/handbook/analytics) section are
|
||||
recalculated.
|
||||
|
||||
## Statistic sections on the detail page
|
||||
|
||||
- **Rating overview:** usefulness & usability as an average with progress
|
||||
bars.
|
||||
- **Score distribution:** number of ratings per star (1★–5★).
|
||||
- **History:** line chart of combined/individual values over time
|
||||
(only visible once there are several ratings).
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools/{id}/ratings`](/docs/reference/endpoints/ratings#createRating) — Submit a rating
|
||||
- [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listToolRatings) — Ratings of a tool
|
||||
@@ -0,0 +1,70 @@
|
||||
|
||||
# Data model
|
||||
|
||||
This chapter explains the central data objects of toolr at the application
|
||||
level. The complete, automatically generated reference of all fields,
|
||||
types and constraints can be found in the
|
||||
[API reference](/docs/reference/schemas/tool).
|
||||
|
||||
## Tool
|
||||
|
||||
The heart of it all: a tool recorded in the catalog.
|
||||
|
||||
| Property | Description |
|
||||
| --- | --- |
|
||||
| `id` | Unique identifier |
|
||||
| `name` | Display name |
|
||||
| `description` | Description (what does the tool do?) |
|
||||
| `category` | Category assignment |
|
||||
| `websiteUrl` | Official website (optional) |
|
||||
| `iconUrl` | Logo/icon URL (optional) |
|
||||
| `features` | List of capabilities |
|
||||
| `tags` | List of keywords |
|
||||
| `createdAt` / `updatedAt` | Timestamps |
|
||||
| `createdBy` | Person who created it |
|
||||
| `deletedAt` / `deletedBy` | Soft deletion (trash) |
|
||||
|
||||
Input forms use the derived schemas
|
||||
[`ToolInput`](/docs/reference/schemas/toolinput) and
|
||||
[`ToolUpdate`](/docs/reference/schemas/toolupdate).
|
||||
Aggregated views are provided by [`ToolWithStats`](/docs/reference/schemas/toolwithstats)
|
||||
(e.g. with average rating).
|
||||
|
||||
## Rating (Bewertung)
|
||||
|
||||
A single rating for a tool:
|
||||
|
||||
- `usefulness` (Nützlichkeit, 1–5) and `usability` (Bedienbarkeit, 1–5)
|
||||
- optional `comment` and a display name (`reviewerName`)
|
||||
- timestamp
|
||||
|
||||
Input schema: [`RatingInput`](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## User & Auth
|
||||
|
||||
- [`User`](/docs/reference/schemas/user) — user account with role (User/Admin)
|
||||
and plan (Free/Premium/Enterprise).
|
||||
- [`AuthUser`](/docs/reference/schemas/authuser) — the logged-in profile
|
||||
including `entitlements` (available features).
|
||||
- [`UserPreferences`](/docs/reference/schemas/userpreferences) — view and
|
||||
density preferences as well as the `watchlist` (list of tool IDs).
|
||||
|
||||
## Analytics
|
||||
|
||||
The statistics endpoints provide aggregated data:
|
||||
|
||||
- [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary) — global
|
||||
metrics (number of tools/ratings, categories, average).
|
||||
- [`TopToolEntry`](/docs/reference/schemas/TopToolEntry) — an entry of the
|
||||
top tools.- [`CategoryStats`](/docs/reference/schemas/categorystats) — number of tools per
|
||||
category.
|
||||
- [`RatingDistribution`](/docs/reference/schemas/ratingdistribution) —
|
||||
score distribution (usefulness & usability).
|
||||
- [`ScoreBucket`](/docs/reference/schemas/scorebucket) — a value bucket.
|
||||
|
||||
## Additional
|
||||
|
||||
- [`VersionInfo`](/docs/reference/schemas/versioninfo) — version, commit SHA,
|
||||
build date and trash retention of the running instance.
|
||||
- [`AuditLog`](/docs/reference/schemas/auditlog) — a log entry
|
||||
(action, entity, timestamp, actor, changes).
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# Getting Started
|
||||
|
||||
This page guides you through the most important workflows in toolr — from your
|
||||
first visit to creating and rating a tool.
|
||||
|
||||
## 1. Sign in
|
||||
|
||||
Most actions (create a tool, rate, watchlist, compare) require
|
||||
an account. Click **Sign in** in the bottom left corner. Depending on the
|
||||
instance configuration you have two options:
|
||||
|
||||
- **Local accounts:** username + password. Access is created by an admin
|
||||
(see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** sign in with the configured identity provider (e.g.
|
||||
Keycloak).
|
||||
|
||||
Which mode is active is shown by the
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode) endpoint. Details
|
||||
can be found in the [Sign in & account](/docs/handbook/konto) section.
|
||||
|
||||
## 2. Find tools
|
||||
|
||||
Open the **Browse tools** section:
|
||||
|
||||
- **Search** — full-text search across name & description (shortcut `/`).
|
||||
- **Filter** — by category, tags, features and minimum rating
|
||||
(`minRating`).
|
||||
- **Sort** — by newest, top-rated, most rated, name
|
||||
(ascending/descending) or last update.
|
||||
|
||||
All options in detail: [Find & browse tools](/docs/handbook/tools-finden).
|
||||
|
||||
## 3. Create a tool
|
||||
|
||||
Go to **Add tool** and fill in the form. Details for each field can be found
|
||||
in the [Create a tool](/docs/handbook/tool-anlegen) section and in the
|
||||
[field reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
## 4. Rate
|
||||
|
||||
On the detail page of a tool you can submit **usefulness** and **usability**
|
||||
(1–5 each) and optionally leave a comment. Your
|
||||
rating is immediately reflected in the statistics.
|
||||
See [Rating](/docs/handbook/bewerten).
|
||||
|
||||
## 5. Further reading
|
||||
|
||||
- [Compare tools](/docs/handbook/vergleichen)
|
||||
- [Watchlist](/docs/handbook/watchlist)
|
||||
- [Analytics](/docs/handbook/analytics)
|
||||
- [Plans & permissions](/docs/handbook/plaene)
|
||||
- [Administration](/docs/handbook/administration)
|
||||
@@ -0,0 +1,51 @@
|
||||
|
||||
# Welcome to toolr
|
||||
|
||||
toolr is a platform for **discovering, rating and comparing development
|
||||
tools**. Users maintain a shared catalog of tools, submit ratings
|
||||
(usefulness & usability) and use statistics to make the right choice.
|
||||
|
||||
## What can you do with toolr?
|
||||
|
||||
| Function | Description | Visibility |
|
||||
| --- | --- | --- |
|
||||
| **Browse tools** | Filter, sort and search the catalog | Everyone |
|
||||
| **Create a tool** | Add a new tool with description, category, features & tags | Logged in |
|
||||
| **Edit/delete tools** | Maintain your own tools (creator or admin) | Logged in |
|
||||
| **Rate** | Submit usefulness & usability (1–5) plus a comment | Logged in |
|
||||
| **Watchlist** | Save tools as favorites | Premium |
|
||||
| **Compare** | View tools side by side | Premium |
|
||||
| **Record costs** | Enter license and cost models per tool | Premium |
|
||||
| **Analytics** | Statistics, top tools, distributions | Everyone |
|
||||
| **Trash** | Restore soft-deleted tools or delete them permanently | Premium |
|
||||
| **Admin** | User management, audit log, system information | Admin |
|
||||
| **Redundancy detection** | Automatic duplicate detection | Admin |
|
||||
|
||||
## How this documentation is organized
|
||||
|
||||
- **User Guide** (these pages): step-by-step instructions for all
|
||||
functions — from the [Getting Started](/docs/handbook/getting-started) to
|
||||
[Administration](/docs/handbook/administration).
|
||||
- **API Reference**: automatically generated from the OpenAPI specification —
|
||||
all [endpoints](/docs/reference/endpoints/tools) and
|
||||
[data fields](/docs/reference/schemas/toolinput) of the current version.
|
||||
- **Release Notes**: what is new in each [version](/docs/releases/v0.8.1).
|
||||
|
||||
## Getting started
|
||||
|
||||
The fastest way:
|
||||
|
||||
1. **Sign in** — without an account you can only browse
|
||||
(see [Getting Started](/docs/handbook/getting-started#1-anmelden)).
|
||||
2. **Find tools** — search, filters and sorting in the
|
||||
[Browse tools](/docs/handbook/tools-finden) section.
|
||||
3. **Create a tool** — via "Add tool"
|
||||
([guide](/docs/handbook/tool-anlegen)).
|
||||
4. **Rate** — on the detail page of a tool
|
||||
([guide](/docs/handbook/bewerten)).
|
||||
|
||||
## Contact & source code
|
||||
|
||||
The source code is available at
|
||||
[git.kubebase.de/admin/tool-evaluator](https://git.kubebase.de/admin/tool-evaluator) —
|
||||
you can reach it at any time via the repository icon in the top right corner.
|
||||
@@ -3,102 +3,136 @@
|
||||
"slug": "index",
|
||||
"file": "index.md",
|
||||
"title": "Überblick",
|
||||
"order": 1
|
||||
"order": 1,
|
||||
"fileEn": "index.en.md",
|
||||
"titleEn": "Overview"
|
||||
},
|
||||
{
|
||||
"slug": "getting-started",
|
||||
"file": "getting-started.md",
|
||||
"title": "Erste Schritte",
|
||||
"order": 2
|
||||
"order": 2,
|
||||
"fileEn": "getting-started.en.md",
|
||||
"titleEn": "Getting Started"
|
||||
},
|
||||
{
|
||||
"slug": "konto",
|
||||
"file": "konto.md",
|
||||
"title": "Anmelden & Konto",
|
||||
"order": 3
|
||||
"order": 3,
|
||||
"fileEn": "konto.en.md",
|
||||
"titleEn": "Login & Account"
|
||||
},
|
||||
{
|
||||
"slug": "tools-finden",
|
||||
"file": "tools-finden.md",
|
||||
"title": "Tools finden & durchsuchen",
|
||||
"order": 4
|
||||
"order": 4,
|
||||
"fileEn": "tools-finden.en.md",
|
||||
"titleEn": "Find & browse tools"
|
||||
},
|
||||
{
|
||||
"slug": "tool-anlegen",
|
||||
"file": "tool-anlegen.md",
|
||||
"title": "Tool anlegen",
|
||||
"order": 5
|
||||
"order": 5,
|
||||
"fileEn": "tool-anlegen.en.md",
|
||||
"titleEn": "Create a tool"
|
||||
},
|
||||
{
|
||||
"slug": "tool-bearbeiten",
|
||||
"file": "tool-bearbeiten.md",
|
||||
"title": "Tool bearbeiten & löschen",
|
||||
"order": 6
|
||||
"order": 6,
|
||||
"fileEn": "tool-bearbeiten.en.md",
|
||||
"titleEn": "Edit & delete tools"
|
||||
},
|
||||
{
|
||||
"slug": "bewerten",
|
||||
"file": "bewerten.md",
|
||||
"title": "Bewerten",
|
||||
"order": 7
|
||||
"order": 7,
|
||||
"fileEn": "bewerten.en.md",
|
||||
"titleEn": "Rating"
|
||||
},
|
||||
{
|
||||
"slug": "watchlist",
|
||||
"file": "watchlist.md",
|
||||
"title": "Watchlist",
|
||||
"order": 8
|
||||
"order": 8,
|
||||
"fileEn": "watchlist.en.md",
|
||||
"titleEn": "Watchlist"
|
||||
},
|
||||
{
|
||||
"slug": "vergleichen",
|
||||
"file": "vergleichen.md",
|
||||
"title": "Vergleichen",
|
||||
"order": 9
|
||||
"order": 9,
|
||||
"fileEn": "vergleichen.en.md",
|
||||
"titleEn": "Compare"
|
||||
},
|
||||
{
|
||||
"slug": "analytics",
|
||||
"file": "analytics.md",
|
||||
"title": "Analytics",
|
||||
"order": 10
|
||||
"order": 10,
|
||||
"fileEn": "analytics.en.md",
|
||||
"titleEn": "Analytics"
|
||||
},
|
||||
{
|
||||
"slug": "plaene",
|
||||
"file": "plaene.md",
|
||||
"title": "Pläne & Berechtigungen",
|
||||
"order": 11
|
||||
"order": 11,
|
||||
"fileEn": "plaene.en.md",
|
||||
"titleEn": "Plans & Permissions"
|
||||
},
|
||||
{
|
||||
"slug": "kosten",
|
||||
"file": "kosten.md",
|
||||
"title": "Kosten erfassen",
|
||||
"order": 12
|
||||
"order": 12,
|
||||
"fileEn": "kosten.en.md",
|
||||
"titleEn": "Recording Costs"
|
||||
},
|
||||
{
|
||||
"slug": "administration",
|
||||
"file": "administration.md",
|
||||
"title": "Administration",
|
||||
"order": 13
|
||||
"order": 13,
|
||||
"fileEn": "administration.en.md",
|
||||
"titleEn": "Administration"
|
||||
},
|
||||
{
|
||||
"slug": "redundanz",
|
||||
"file": "redundanz.md",
|
||||
"title": "Redundanz-Dashboard",
|
||||
"order": 14
|
||||
"order": 14,
|
||||
"fileEn": "redundanz.en.md",
|
||||
"titleEn": "Redundancy dashboard"
|
||||
},
|
||||
{
|
||||
"slug": "papierkorb",
|
||||
"file": "papierkorb.md",
|
||||
"title": "Papierkorb",
|
||||
"order": 15
|
||||
"order": 15,
|
||||
"fileEn": "papierkorb.en.md",
|
||||
"titleEn": "Trash"
|
||||
},
|
||||
{
|
||||
"slug": "tastatur",
|
||||
"file": "tastatur.md",
|
||||
"title": "Tastenkürzel & Kommandopalette",
|
||||
"order": 16
|
||||
"order": 16,
|
||||
"fileEn": "tastatur.en.md",
|
||||
"titleEn": "Keyboard shortcuts & command palette"
|
||||
},
|
||||
{
|
||||
"slug": "datenmodell",
|
||||
"file": "datenmodell.md",
|
||||
"title": "Datenmodell",
|
||||
"order": 17
|
||||
"order": 17,
|
||||
"fileEn": "datenmodell.en.md",
|
||||
"titleEn": "Data model"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,52 @@
|
||||
|
||||
# Login & Account
|
||||
|
||||
## Logging in
|
||||
|
||||
Click **Login** at the bottom left of the sidebar. Depending on the
|
||||
configuration of the instance:
|
||||
|
||||
- **Local accounts:** enter username and password. The accounts are created
|
||||
by an admin (see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** you are redirected to the configured identity provider and
|
||||
log in there.
|
||||
|
||||
The active mode is available at the endpoint
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode).
|
||||
|
||||
> You can reach the login page directly at `/login`. After a successful
|
||||
> login you are redirected back to the page you originally requested.
|
||||
|
||||
## User profile
|
||||
|
||||
You can see your profile (avatar, name, email, plan) at the bottom left in
|
||||
the user menu. There you have the following actions available:
|
||||
|
||||
- **Watchlist** — your saved tools (only with the corresponding plan).
|
||||
- **Trash** — restorable, deleted tools (Premium/Enterprise).
|
||||
- **Change password** — directly in toolr for local accounts; for OIDC
|
||||
accounts, password management is offered in the identity provider.
|
||||
- **Logout** — ends your session.
|
||||
|
||||
## Changing your password (local account)
|
||||
|
||||
1. Open the user menu at the bottom left.
|
||||
2. Select **Change password**.
|
||||
3. Enter the **current** and a **new** password (min. 6 characters) and
|
||||
confirm it.
|
||||
4. Save — the password takes effect immediately.
|
||||
|
||||
API reference: [`POST /auth/me/password`](/docs/reference/endpoints/auth#changeMyPassword).
|
||||
|
||||
## Display settings
|
||||
|
||||
Using the buttons at the top right you can:
|
||||
|
||||
- switch the **language** (German / English),
|
||||
- toggle the **theme** (Light / Dark / System),
|
||||
- adjust the **list view** and **density** in the Browse tools section
|
||||
(see [Finding & browsing tools](/docs/handbook/tools-finden)).
|
||||
|
||||
Your preferences (incl. watchlist) are saved at the endpoint
|
||||
[`GET /auth/me/preferences`](/docs/reference/endpoints/auth#getMePreferences)
|
||||
and updated via [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updateMePreferences).
|
||||
@@ -0,0 +1,35 @@
|
||||
|
||||
# Recording Costs
|
||||
|
||||
On the detail page of a tool you can enter cost and license models so that
|
||||
the total costs per tool become transparent.
|
||||
|
||||
> Costs is a **premium feature** (`costs`, Premium/Enterprise). Admins always
|
||||
> have access.
|
||||
|
||||
## Adding costs
|
||||
|
||||
Click **Add costs** in the costs section of the detail page and fill out the
|
||||
form:
|
||||
|
||||
| Field | Notes |
|
||||
| --- | --- |
|
||||
| **License type** | Free / Subscription / One-Time / Usage-Based |
|
||||
| **Billing period** | Only for "Subscription": Monthly / Quarterly / Annually |
|
||||
| **Costs** | Amount as a number |
|
||||
| **Currency** | EUR / USD / GBP / CHF |
|
||||
| **Notes** | Optional free text |
|
||||
|
||||
Saving creates the entry. Each cost entry is displayed as a card with
|
||||
license badge, billing period, amount (`Amount Currency` or "Free") and
|
||||
notes.
|
||||
|
||||
## Editing & deleting costs
|
||||
|
||||
Hovering over a cost card shows the **Edit** (pencil) and **Delete** (trash)
|
||||
actions.
|
||||
|
||||
## API
|
||||
|
||||
The cost data is managed via the tool endpoints
|
||||
(see [API reference](/docs/reference/endpoints/tools)).
|
||||
@@ -0,0 +1,40 @@
|
||||
|
||||
# Trash
|
||||
|
||||
The **trash** (`/trash`) contains soft-deleted tools. With trash access
|
||||
they can be restored; permanent deletion is reserved for admins.
|
||||
|
||||
> The trash is a **premium feature** (`trash`, Premium/Enterprise).
|
||||
> Admins always have access.
|
||||
|
||||
## Access
|
||||
|
||||
The trash can be reached via the user menu or the sidebar.
|
||||
Without the `trash` permission, a hint about changing the plan appears.
|
||||
|
||||
## Restoring
|
||||
|
||||
- Select one or more tools (checkboxes).
|
||||
- Click on **Restore (N)** — the tools appear again in all
|
||||
public views.
|
||||
|
||||
> Restoring is available to anyone with trash access.
|
||||
|
||||
## Permanently delete (admin only)
|
||||
|
||||
- **Delete (N)** **permanently** removes the selected tools — including
|
||||
all ratings, costs and links. This cannot be undone.
|
||||
- **Empty trash** permanently removes all soft-deleted tools.
|
||||
|
||||
## Table
|
||||
|
||||
The trash lists: name, category, **Deleted on** (`tt.MM.jjjj HH:mm`),
|
||||
**Deleted by** as well as actions (Restore; Delete admin only). The search
|
||||
filters by name.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /tools/trash`](/docs/reference/endpoints/tools#listTrashedTools) — list
|
||||
- [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoreTools) — restore
|
||||
- [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deleteTrashedTools) — permanently delete (admin)
|
||||
- [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptyTrash) — empty trash (admin)
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# Plans & Permissions
|
||||
|
||||
toolr distinguishes **plans** (tier) and **roles**. Admins bypass all feature
|
||||
restrictions.
|
||||
|
||||
## Plans
|
||||
|
||||
| Plan | Description |
|
||||
| --- | --- |
|
||||
| **Free** | Basic functions: search, filter, view, analytics |
|
||||
| **Premium** | Additionally watchlist, compare, trash, costs |
|
||||
| **Enterprise** | All premium features + extended support |
|
||||
|
||||
### Feature permissions
|
||||
|
||||
Premium/Enterprise unlock the following features:
|
||||
|
||||
| Feature | Function | Learn more |
|
||||
| --- | --- | --- |
|
||||
| `compare` | Compare tools | [Compare](/docs/handbook/vergleichen) |
|
||||
| `watchlist` | Favorites list | [Watchlist](/docs/handbook/watchlist) |
|
||||
| `trash` | Trash (soft-deleted tools) | [Trash](/docs/handbook/papierkorb) |
|
||||
| `costs` | Record cost/license models | [Recording costs](/docs/handbook/kosten) |
|
||||
|
||||
If you are missing a feature, the app shows an **upgrade notice** with a link
|
||||
to the plan management.
|
||||
|
||||
## Roles
|
||||
|
||||
| Role | Permissions |
|
||||
| --- | --- |
|
||||
| **User** | Standard account: create/rate tools, edit your own tools |
|
||||
| **Admin** | All user rights + administration, audit log, redundancy, empty trash, tool links |
|
||||
|
||||
Admins pass **all** feature checks — even without a premium plan.
|
||||
|
||||
## Plan/role management
|
||||
|
||||
The assignment of role and plan is managed by admins in the
|
||||
[Administration](/docs/handbook/administration) section (tab "Users").
|
||||
@@ -0,0 +1,38 @@
|
||||
|
||||
# Redundancy dashboard
|
||||
|
||||
The **Redundancy dashboard** (`/admin/redundancy`) is an admin tool for
|
||||
automatic detection of duplicate or strongly overlapping tools — per
|
||||
category — including cost and rating comparison.
|
||||
|
||||
> Access is reserved exclusively for admins (the API is
|
||||
> admin-protected).
|
||||
|
||||
## Layout
|
||||
|
||||
- **Per category** a group is shown: name of the category,
|
||||
number of tools and comparisons as well as the **total monthly costs**
|
||||
if applicable (e.g. `€X.XX/mo total`).
|
||||
- Each tool is displayed as a card: name, monthly costs, number of
|
||||
ratings, combined rating, license badges and number of features.
|
||||
|
||||
## Comparisons & recommendations
|
||||
|
||||
For each tool pair the following appears:
|
||||
|
||||
- Tool A vs. Tool B, each with rating (`X.X ★`) and monthly costs.
|
||||
- **Overlap** in percent (progress bar in the middle).
|
||||
- A **recommendation** with confidence color:
|
||||
- **high** (green), **medium** (yellow), **low** (gray)
|
||||
- The recommended, better tool is marked with a "thumbs up" and justified.
|
||||
|
||||
## Manual rating
|
||||
|
||||
You can rate a pair manually: click on Tool A or Tool B to
|
||||
record which one is better. The selection is saved and the
|
||||
display is updated.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /api/admin/redundancy`](#) — load data (admin-protected)
|
||||
- [`POST /api/admin/redundancy/evaluate`](#) — save manual rating
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
# Keyboard shortcuts & command palette
|
||||
|
||||
## Command palette
|
||||
|
||||
The command palette is the central quick navigation:
|
||||
|
||||
- Open with **`⌘K`** (macOS) or **`Ctrl+K`** (Windows/Linux).
|
||||
- Alternatively via the search bar at the top right ("Search tools… ⌘K") or the
|
||||
search icon on mobile devices.
|
||||
|
||||
### Empty state
|
||||
|
||||
Without input, the palette shows:
|
||||
|
||||
- **Recently viewed** — the last 5 tools you visited.
|
||||
- **Navigation** — browse tools, add tool, analytics as well as
|
||||
(depending on permissions) watchlist, trash and admin.
|
||||
|
||||
### Search
|
||||
|
||||
Type to search for tools live (max. 10 results, incl. rating
|
||||
`X.X★`).
|
||||
|
||||
## Overview of keyboard shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| `⌘K` / `Ctrl+K` | Open command palette |
|
||||
| `/` | Focus search in the "Browse tools" area |
|
||||
|
||||
## Additional notes
|
||||
|
||||
- **Recently viewed** is stored locally in the browser (max. 5 entries).
|
||||
- The sidebar (left navigation) can be collapsed on desktop; the
|
||||
breadcrumb at the top shows your current location.
|
||||
@@ -0,0 +1,46 @@
|
||||
|
||||
# Create a tool
|
||||
|
||||
To add a new tool to the catalog, click **Add tool**
|
||||
(`/tools/new`). Creating a tool requires an account — without being signed in
|
||||
a notice with a login button appears.
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Name** | Yes | At least 2 characters |
|
||||
| **Category** | Yes | Dropdown; new categories can be created directly |
|
||||
| **Website URL** | No | Valid URL (e.g. `https://...`) |
|
||||
| **Icon / Logo URL** | No | Valid URL; preview is shown live |
|
||||
| **Description** | Yes | At least 10 characters; describe what the tool does |
|
||||
| **Features** | No | Dynamic list with autocomplete (max. 6) |
|
||||
| **Tags** | No | Dynamic list with autocomplete |
|
||||
|
||||
Next to each field, the **? icon** takes you directly to the corresponding
|
||||
field description in the [data model reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
### Category
|
||||
|
||||
- Type to search for existing categories.
|
||||
- Select **+ Create "..."** to create a new category.
|
||||
|
||||
### Features & tags
|
||||
|
||||
- **Add feature** / **Add tag** appends a new row.
|
||||
- The input fields suggest existing features/tags
|
||||
(autocomplete, max. 6 suggestions).
|
||||
- Use the **×** button to remove individual rows.
|
||||
- Features and tags help with filtering and finding tools again.
|
||||
|
||||
## Save
|
||||
|
||||
Click **Add tool**. After successful creation you will be redirected to the
|
||||
detail page of the new tool.
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools`](/docs/reference/endpoints/tools#createTool) — create a tool
|
||||
- [`GET /categories`](/docs/reference/endpoints/tools#listCategories) — categories
|
||||
- [`GET /features/all`](/docs/reference/endpoints/tools#listAllFeatures) — features
|
||||
- [`GET /tags/all`](/docs/reference/endpoints/tools#listAllTags) — tags
|
||||
@@ -0,0 +1,32 @@
|
||||
|
||||
# Edit & delete tools
|
||||
|
||||
## Editing
|
||||
|
||||
On the detail page of a tool you will find the **Edit** button
|
||||
(only for the person who created the tool, as well as for admins).
|
||||
|
||||
The edit page (`/tools/:id/edit`) contains the same fields as when
|
||||
creating (name, category, website/icon URL, description, features, tags) —
|
||||
already filled with the current values.
|
||||
|
||||
- **Save** applies the changes.
|
||||
- **Cancel** takes you back to the detail page.
|
||||
|
||||
API reference: [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updateTool).
|
||||
|
||||
## Deleting
|
||||
|
||||
Via **Delete** on the detail page the tool is removed. The behavior
|
||||
depends on your plan:
|
||||
|
||||
- **With trash access** (Premium/Enterprise or Admin): the tool is
|
||||
**soft deleted** — it disappears from all public views, but can
|
||||
be restored or permanently deleted in the [trash](/docs/handbook/papierkorb).
|
||||
- **Without trash access:** the tool is **permanently** deleted and cannot
|
||||
be restored.
|
||||
|
||||
Deletion is only possible for the person who created the tool, as well as
|
||||
for admins.
|
||||
|
||||
API reference: [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deleteTool).
|
||||
@@ -0,0 +1,66 @@
|
||||
|
||||
# Find & browse tools
|
||||
|
||||
The **Browse tools** section (`/tools`) is your entry point to the catalog.
|
||||
Here you combine search, filters and sorting to find exactly the tools
|
||||
you are interested in.
|
||||
|
||||
## Search
|
||||
|
||||
- The **search bar** searches name and description (full text).
|
||||
- Shortcut: Press **`/`** to focus the search.
|
||||
- The input is debounced so that filtering happens immediately with each
|
||||
keystroke.
|
||||
|
||||
## Filter
|
||||
|
||||
Via the **Filter** button (with a badge for the number of active filters)
|
||||
you open the filter popover with:
|
||||
|
||||
- **Tags** — selection via checkboxes (scrollable list).
|
||||
- **Features** — selection via checkboxes.
|
||||
- **Minimum rating** — slider from 0 to 5 (in steps of 0.5); shows
|
||||
e.g. "3.0+".
|
||||
|
||||
Active filters appear as **removable chips** above the result list.
|
||||
Use **Reset filters** or **Remove all** to clear them again.
|
||||
|
||||
## Sort
|
||||
|
||||
The **Sort** dropdown offers the following options:
|
||||
|
||||
| Sort | Description |
|
||||
| --- | --- |
|
||||
| Newest | New tools first |
|
||||
| Top rated | By combined rating |
|
||||
| Most rated | By number of ratings |
|
||||
| Name (A–Z) | Alphabetically ascending |
|
||||
| Name (Z–A) | Alphabetically descending |
|
||||
| Last updated | By last update |
|
||||
|
||||
## View & density
|
||||
|
||||
- **Switch view:** grid / table / rows.
|
||||
- **Density:** comfortable / compact (slider).
|
||||
|
||||
Your selection is saved — locally in the browser and, for logged-in users,
|
||||
additionally on the server in the preferences. View, density, search, filters
|
||||
and sorting are reflected in the URL so you can share results.
|
||||
|
||||
## Table view
|
||||
|
||||
In the table view the columns **Tool**, **Rating** and **Number of
|
||||
ratings** are sortable. Hovering over a row shows a preview
|
||||
with rating details, tags and mini bars.
|
||||
|
||||
## Selecting for comparison & watchlist
|
||||
|
||||
- On every card/row you find a **compare icon** that lets you add tools to the
|
||||
[compare bar](/docs/handbook/vergleichen).
|
||||
- The **bookmark icon** saves tools to your
|
||||
[watchlist](/docs/handbook/watchlist) (only with the corresponding plan).
|
||||
|
||||
## API
|
||||
|
||||
All search, filter and sort parameters correspond to the query parameters of
|
||||
[`GET /tools`](/docs/reference/endpoints/tools#listTools).
|
||||
@@ -0,0 +1,42 @@
|
||||
|
||||
# Compare
|
||||
|
||||
With the compare function you can put several tools **side by side** —
|
||||
ideal for making a well-informed decision.
|
||||
|
||||
> Comparing is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Selecting tools
|
||||
|
||||
1. In the **Browse tools** section, click the **compare icon** (scales) on
|
||||
each card/row.
|
||||
2. The **compare bar** appears at the bottom with the selected tools as
|
||||
chips. You can remove individual tools (×) or clear the selection.
|
||||
3. Click **Compare (N)** to go to the compare view.
|
||||
|
||||
> Without a premium plan the button is locked (lock icon). The dialog takes
|
||||
> you to the plan switch
|
||||
> (see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## The compare view
|
||||
|
||||
The view shows a table with one column per tool. Rows:
|
||||
|
||||
| Row | Content |
|
||||
| --- | --- |
|
||||
| **Rating** | Stars + value (e.g. `4.2/5`) |
|
||||
| **Usefulness** | Value (X.X/5) |
|
||||
| **Usability** | Value (X.X/5) |
|
||||
| **Number of ratings** | Count |
|
||||
| **Description** | Text |
|
||||
| **Features** | Badges |
|
||||
| **Tags** | Badges |
|
||||
| **Last updated** | Date |
|
||||
|
||||
The **best value** per row is highlighted (with trophy icon).
|
||||
|
||||
## API
|
||||
|
||||
The compare view reads the data via
|
||||
[`GET /compare`](/docs/reference/endpoints/tools#listCompareTools).
|
||||
@@ -0,0 +1,33 @@
|
||||
|
||||
# Watchlist
|
||||
|
||||
The **watchlist** is a personal favorites list. You can open and compare the
|
||||
tools in it at any time with a click.
|
||||
|
||||
> The watchlist is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Prerequisite
|
||||
|
||||
You need a plan with the `watchlist` permission. If it is missing, a note
|
||||
about switching plans appears at the bookmark
|
||||
(see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## Saving a tool
|
||||
|
||||
- On every card/row in the **Browse tools** section you will find the
|
||||
**bookmark icon**.
|
||||
- A click saves the tool to your watchlist — the icon becomes filled.
|
||||
- Clicking it again removes it.
|
||||
|
||||
## Viewing the watchlist
|
||||
|
||||
Open the watchlist via the user menu or the sidebar. It shows all saved tools
|
||||
as cards. The filled bookmark on a card removes the tool from the list.
|
||||
|
||||
## Where is the watchlist stored?
|
||||
|
||||
The watchlist is a list of tool IDs in your **user preferences**. This way it
|
||||
is linked to your account across devices.
|
||||
|
||||
API reference: [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getMeWatchlist).
|
||||
@@ -0,0 +1,35 @@
|
||||
# v0.8.2 — Release Notes
|
||||
|
||||
**Date:** 2026-08-04 · **Tag:** [`v0.8.2`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.2)
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- **Mobile navigation in the docs**: The left navigation bar (manual,
|
||||
endpoints, schemas) was completely hidden below `lg` (1024px).
|
||||
There is now a menu button in the header that opens a side
|
||||
navigation drawer with the same content — on small screens
|
||||
the docs remain fully navigable.
|
||||
- **Version dropdown shows the selected version**: When switching to a
|
||||
different release (`/docs/releases/vX.Y.Z`), the dropdown wrongly stayed on
|
||||
"current". The displayed version is now also derived from the releases route.
|
||||
|
||||
## API changes
|
||||
|
||||
- No changes to the API.
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged.
|
||||
- **Migration:** none.
|
||||
- **Breaking changes:** none.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- Manual & reference apply to the current version; older versions show
|
||||
their release notes and a reference snapshot, if generated at release time
|
||||
(`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`).
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`33cf261`](https://git.kubebase.de/admin/tool-evaluator/commit/33cf261)
|
||||
- Tag: [`v0.8.2`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.2)
|
||||
@@ -0,0 +1,61 @@
|
||||
|
||||
# Administration
|
||||
|
||||
The **Admin** area (`/admin`) is exclusively accessible to admins.
|
||||
Without the admin role, access is denied.
|
||||
|
||||
> At the top right, the **Redundancy dashboard** button leads to the automatic
|
||||
> duplicate detection (see [Redundancy](/docs/handbook/redundanz)).
|
||||
|
||||
## "Users" tab
|
||||
|
||||
Management of local accounts.
|
||||
|
||||
- **Add user:** username (required), password (at least 6 characters),
|
||||
email (optional), **role** (User/Admin), **plan** (Free/Premium/Enterprise).
|
||||
- **Edit user:** set role, plan and (for local accounts) a new password.
|
||||
For OIDC accounts, password management is offered in the identity provider
|
||||
(e.g. Keycloak).
|
||||
- **Delete user:** permanently removes the account (not for your own account).
|
||||
|
||||
API reference:
|
||||
[`POST /users`](/docs/reference/endpoints/users#createUser),
|
||||
[`PATCH /users/{id}`](/docs/reference/endpoints/users#updateUser),
|
||||
[`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteUser).
|
||||
|
||||
## "Tools" tab
|
||||
|
||||
Central access to the tool catalog.
|
||||
|
||||
- **Search** for tools.
|
||||
- View, edit or move individual tools to the trash.
|
||||
- **Bulk action:** select multiple tools and move them to the trash
|
||||
(confirmation dialog; soft-deleted tools are removed from all public views
|
||||
and can be restored or permanently deleted).
|
||||
|
||||
## "Audit log" tab
|
||||
|
||||
Chronological log of all creation, change and deletion operations
|
||||
(max. 100 entries): action, entity + ID, timestamp, executing person and
|
||||
changed fields.
|
||||
|
||||
API reference: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs).
|
||||
|
||||
## "System" tab
|
||||
|
||||
Version information of the running instance:
|
||||
|
||||
- **Version** (e.g. `v0.8.1`),
|
||||
- **Commit** (7-digit SHA, linked to the repository),
|
||||
- **Build date**,
|
||||
- **Trash retention** ("N days" or "Forever").
|
||||
|
||||
## Tool links (Admin)
|
||||
|
||||
On the detail page of a tool you can manage **links** as an admin
|
||||
(own/"manual" as well as automatically detected ones):
|
||||
|
||||
- **Link tool:** dialog with tool ID, **relationship type**
|
||||
(Similar / Replaces / Superseded by) and optional notes.
|
||||
- Relationship types are displayed as badges on the detail page.
|
||||
- Manual links can be removed again via the trash icon.
|
||||
@@ -0,0 +1,29 @@
|
||||
|
||||
# Analytics
|
||||
|
||||
The **Analytics** area (`/analytics`) is a public dashboard with
|
||||
metrics and charts based on all tools and ratings.
|
||||
|
||||
## Metrics (KPI cards)
|
||||
|
||||
- **Number of tools** — how many tools are recorded in the catalog.
|
||||
- **Number of ratings** — how many ratings were submitted in total.
|
||||
- **Active categories** — how many categories exist.
|
||||
- **Average rating** — global combined value.
|
||||
|
||||
## Charts
|
||||
|
||||
| Chart | Content |
|
||||
| --- | --- |
|
||||
| **Top 8 tools** | Bar chart of the tools with the highest combined score (0–5) |
|
||||
| **Tools per category** | Radar chart of the number of tools per category |
|
||||
| **Score distribution** | Two horizontal bar charts (usefulness & usability) per star |
|
||||
|
||||
The charts are interactive (tooltips on hover).
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getAnalyticsSummary)
|
||||
- [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#getTopTools)
|
||||
- [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getAnalyticsByCategory)
|
||||
- [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getRatingDistribution)
|
||||
@@ -0,0 +1,39 @@
|
||||
|
||||
# Rating
|
||||
|
||||
On the detail page of a tool you can share your experience. Click on
|
||||
**Submit a rating** (requires an account).
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Usefulness** | Yes | 1–5 stars |
|
||||
| **Usability** | Yes | 1–5 stars |
|
||||
| **Comment** | No | Free text |
|
||||
| **Name** | No | Defaults to "Anonymous" |
|
||||
|
||||
Next to the fields, the **? icon** links directly to the associated field
|
||||
description in the [data model reference](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## What happens after submitting?
|
||||
|
||||
- Your rating is saved immediately and appears in the **rating list** of the
|
||||
detail page.
|
||||
- The **averages** (usefulness, usability, combined) and the **score
|
||||
distribution** are updated.
|
||||
- The **statistics** in the [Analytics](/docs/handbook/analytics) section are
|
||||
recalculated.
|
||||
|
||||
## Statistic sections on the detail page
|
||||
|
||||
- **Rating overview:** usefulness & usability as an average with progress
|
||||
bars.
|
||||
- **Score distribution:** number of ratings per star (1★–5★).
|
||||
- **History:** line chart of combined/individual values over time
|
||||
(only visible once there are several ratings).
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools/{id}/ratings`](/docs/reference/endpoints/ratings#createRating) — Submit a rating
|
||||
- [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listToolRatings) — Ratings of a tool
|
||||
@@ -0,0 +1,70 @@
|
||||
|
||||
# Data model
|
||||
|
||||
This chapter explains the central data objects of toolr at the application
|
||||
level. The complete, automatically generated reference of all fields,
|
||||
types and constraints can be found in the
|
||||
[API reference](/docs/reference/schemas/tool).
|
||||
|
||||
## Tool
|
||||
|
||||
The heart of it all: a tool recorded in the catalog.
|
||||
|
||||
| Property | Description |
|
||||
| --- | --- |
|
||||
| `id` | Unique identifier |
|
||||
| `name` | Display name |
|
||||
| `description` | Description (what does the tool do?) |
|
||||
| `category` | Category assignment |
|
||||
| `websiteUrl` | Official website (optional) |
|
||||
| `iconUrl` | Logo/icon URL (optional) |
|
||||
| `features` | List of capabilities |
|
||||
| `tags` | List of keywords |
|
||||
| `createdAt` / `updatedAt` | Timestamps |
|
||||
| `createdBy` | Person who created it |
|
||||
| `deletedAt` / `deletedBy` | Soft deletion (trash) |
|
||||
|
||||
Input forms use the derived schemas
|
||||
[`ToolInput`](/docs/reference/schemas/toolinput) and
|
||||
[`ToolUpdate`](/docs/reference/schemas/toolupdate).
|
||||
Aggregated views are provided by [`ToolWithStats`](/docs/reference/schemas/toolwithstats)
|
||||
(e.g. with average rating).
|
||||
|
||||
## Rating (Bewertung)
|
||||
|
||||
A single rating for a tool:
|
||||
|
||||
- `usefulness` (Nützlichkeit, 1–5) and `usability` (Bedienbarkeit, 1–5)
|
||||
- optional `comment` and a display name (`reviewerName`)
|
||||
- timestamp
|
||||
|
||||
Input schema: [`RatingInput`](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## User & Auth
|
||||
|
||||
- [`User`](/docs/reference/schemas/user) — user account with role (User/Admin)
|
||||
and plan (Free/Premium/Enterprise).
|
||||
- [`AuthUser`](/docs/reference/schemas/authuser) — the logged-in profile
|
||||
including `entitlements` (available features).
|
||||
- [`UserPreferences`](/docs/reference/schemas/userpreferences) — view and
|
||||
density preferences as well as the `watchlist` (list of tool IDs).
|
||||
|
||||
## Analytics
|
||||
|
||||
The statistics endpoints provide aggregated data:
|
||||
|
||||
- [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary) — global
|
||||
metrics (number of tools/ratings, categories, average).
|
||||
- [`TopToolEntry`](/docs/reference/schemas/TopToolEntry) — an entry of the
|
||||
top tools.- [`CategoryStats`](/docs/reference/schemas/categorystats) — number of tools per
|
||||
category.
|
||||
- [`RatingDistribution`](/docs/reference/schemas/ratingdistribution) —
|
||||
score distribution (usefulness & usability).
|
||||
- [`ScoreBucket`](/docs/reference/schemas/scorebucket) — a value bucket.
|
||||
|
||||
## Additional
|
||||
|
||||
- [`VersionInfo`](/docs/reference/schemas/versioninfo) — version, commit SHA,
|
||||
build date and trash retention of the running instance.
|
||||
- [`AuditLog`](/docs/reference/schemas/auditlog) — a log entry
|
||||
(action, entity, timestamp, actor, changes).
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# Getting Started
|
||||
|
||||
This page guides you through the most important workflows in toolr — from your
|
||||
first visit to creating and rating a tool.
|
||||
|
||||
## 1. Sign in
|
||||
|
||||
Most actions (create a tool, rate, watchlist, compare) require
|
||||
an account. Click **Sign in** in the bottom left corner. Depending on the
|
||||
instance configuration you have two options:
|
||||
|
||||
- **Local accounts:** username + password. Access is created by an admin
|
||||
(see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** sign in with the configured identity provider (e.g.
|
||||
Keycloak).
|
||||
|
||||
Which mode is active is shown by the
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode) endpoint. Details
|
||||
can be found in the [Sign in & account](/docs/handbook/konto) section.
|
||||
|
||||
## 2. Find tools
|
||||
|
||||
Open the **Browse tools** section:
|
||||
|
||||
- **Search** — full-text search across name & description (shortcut `/`).
|
||||
- **Filter** — by category, tags, features and minimum rating
|
||||
(`minRating`).
|
||||
- **Sort** — by newest, top-rated, most rated, name
|
||||
(ascending/descending) or last update.
|
||||
|
||||
All options in detail: [Find & browse tools](/docs/handbook/tools-finden).
|
||||
|
||||
## 3. Create a tool
|
||||
|
||||
Go to **Add tool** and fill in the form. Details for each field can be found
|
||||
in the [Create a tool](/docs/handbook/tool-anlegen) section and in the
|
||||
[field reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
## 4. Rate
|
||||
|
||||
On the detail page of a tool you can submit **usefulness** and **usability**
|
||||
(1–5 each) and optionally leave a comment. Your
|
||||
rating is immediately reflected in the statistics.
|
||||
See [Rating](/docs/handbook/bewerten).
|
||||
|
||||
## 5. Further reading
|
||||
|
||||
- [Compare tools](/docs/handbook/vergleichen)
|
||||
- [Watchlist](/docs/handbook/watchlist)
|
||||
- [Analytics](/docs/handbook/analytics)
|
||||
- [Plans & permissions](/docs/handbook/plaene)
|
||||
- [Administration](/docs/handbook/administration)
|
||||
@@ -0,0 +1,51 @@
|
||||
|
||||
# Welcome to toolr
|
||||
|
||||
toolr is a platform for **discovering, rating and comparing development
|
||||
tools**. Users maintain a shared catalog of tools, submit ratings
|
||||
(usefulness & usability) and use statistics to make the right choice.
|
||||
|
||||
## What can you do with toolr?
|
||||
|
||||
| Function | Description | Visibility |
|
||||
| --- | --- | --- |
|
||||
| **Browse tools** | Filter, sort and search the catalog | Everyone |
|
||||
| **Create a tool** | Add a new tool with description, category, features & tags | Logged in |
|
||||
| **Edit/delete tools** | Maintain your own tools (creator or admin) | Logged in |
|
||||
| **Rate** | Submit usefulness & usability (1–5) plus a comment | Logged in |
|
||||
| **Watchlist** | Save tools as favorites | Premium |
|
||||
| **Compare** | View tools side by side | Premium |
|
||||
| **Record costs** | Enter license and cost models per tool | Premium |
|
||||
| **Analytics** | Statistics, top tools, distributions | Everyone |
|
||||
| **Trash** | Restore soft-deleted tools or delete them permanently | Premium |
|
||||
| **Admin** | User management, audit log, system information | Admin |
|
||||
| **Redundancy detection** | Automatic duplicate detection | Admin |
|
||||
|
||||
## How this documentation is organized
|
||||
|
||||
- **User Guide** (these pages): step-by-step instructions for all
|
||||
functions — from the [Getting Started](/docs/handbook/getting-started) to
|
||||
[Administration](/docs/handbook/administration).
|
||||
- **API Reference**: automatically generated from the OpenAPI specification —
|
||||
all [endpoints](/docs/reference/endpoints/tools) and
|
||||
[data fields](/docs/reference/schemas/toolinput) of the current version.
|
||||
- **Release Notes**: what is new in each [version](/docs/releases/v0.8.1).
|
||||
|
||||
## Getting started
|
||||
|
||||
The fastest way:
|
||||
|
||||
1. **Sign in** — without an account you can only browse
|
||||
(see [Getting Started](/docs/handbook/getting-started#1-anmelden)).
|
||||
2. **Find tools** — search, filters and sorting in the
|
||||
[Browse tools](/docs/handbook/tools-finden) section.
|
||||
3. **Create a tool** — via "Add tool"
|
||||
([guide](/docs/handbook/tool-anlegen)).
|
||||
4. **Rate** — on the detail page of a tool
|
||||
([guide](/docs/handbook/bewerten)).
|
||||
|
||||
## Contact & source code
|
||||
|
||||
The source code is available at
|
||||
[git.kubebase.de/admin/tool-evaluator](https://git.kubebase.de/admin/tool-evaluator) —
|
||||
you can reach it at any time via the repository icon in the top right corner.
|
||||
@@ -3,102 +3,136 @@
|
||||
"slug": "index",
|
||||
"file": "index.md",
|
||||
"title": "Überblick",
|
||||
"order": 1
|
||||
"order": 1,
|
||||
"fileEn": "index.en.md",
|
||||
"titleEn": "Overview"
|
||||
},
|
||||
{
|
||||
"slug": "getting-started",
|
||||
"file": "getting-started.md",
|
||||
"title": "Erste Schritte",
|
||||
"order": 2
|
||||
"order": 2,
|
||||
"fileEn": "getting-started.en.md",
|
||||
"titleEn": "Getting Started"
|
||||
},
|
||||
{
|
||||
"slug": "konto",
|
||||
"file": "konto.md",
|
||||
"title": "Anmelden & Konto",
|
||||
"order": 3
|
||||
"order": 3,
|
||||
"fileEn": "konto.en.md",
|
||||
"titleEn": "Login & Account"
|
||||
},
|
||||
{
|
||||
"slug": "tools-finden",
|
||||
"file": "tools-finden.md",
|
||||
"title": "Tools finden & durchsuchen",
|
||||
"order": 4
|
||||
"order": 4,
|
||||
"fileEn": "tools-finden.en.md",
|
||||
"titleEn": "Find & browse tools"
|
||||
},
|
||||
{
|
||||
"slug": "tool-anlegen",
|
||||
"file": "tool-anlegen.md",
|
||||
"title": "Tool anlegen",
|
||||
"order": 5
|
||||
"order": 5,
|
||||
"fileEn": "tool-anlegen.en.md",
|
||||
"titleEn": "Create a tool"
|
||||
},
|
||||
{
|
||||
"slug": "tool-bearbeiten",
|
||||
"file": "tool-bearbeiten.md",
|
||||
"title": "Tool bearbeiten & löschen",
|
||||
"order": 6
|
||||
"order": 6,
|
||||
"fileEn": "tool-bearbeiten.en.md",
|
||||
"titleEn": "Edit & delete tools"
|
||||
},
|
||||
{
|
||||
"slug": "bewerten",
|
||||
"file": "bewerten.md",
|
||||
"title": "Bewerten",
|
||||
"order": 7
|
||||
"order": 7,
|
||||
"fileEn": "bewerten.en.md",
|
||||
"titleEn": "Rating"
|
||||
},
|
||||
{
|
||||
"slug": "watchlist",
|
||||
"file": "watchlist.md",
|
||||
"title": "Watchlist",
|
||||
"order": 8
|
||||
"order": 8,
|
||||
"fileEn": "watchlist.en.md",
|
||||
"titleEn": "Watchlist"
|
||||
},
|
||||
{
|
||||
"slug": "vergleichen",
|
||||
"file": "vergleichen.md",
|
||||
"title": "Vergleichen",
|
||||
"order": 9
|
||||
"order": 9,
|
||||
"fileEn": "vergleichen.en.md",
|
||||
"titleEn": "Compare"
|
||||
},
|
||||
{
|
||||
"slug": "analytics",
|
||||
"file": "analytics.md",
|
||||
"title": "Analytics",
|
||||
"order": 10
|
||||
"order": 10,
|
||||
"fileEn": "analytics.en.md",
|
||||
"titleEn": "Analytics"
|
||||
},
|
||||
{
|
||||
"slug": "plaene",
|
||||
"file": "plaene.md",
|
||||
"title": "Pläne & Berechtigungen",
|
||||
"order": 11
|
||||
"order": 11,
|
||||
"fileEn": "plaene.en.md",
|
||||
"titleEn": "Plans & Permissions"
|
||||
},
|
||||
{
|
||||
"slug": "kosten",
|
||||
"file": "kosten.md",
|
||||
"title": "Kosten erfassen",
|
||||
"order": 12
|
||||
"order": 12,
|
||||
"fileEn": "kosten.en.md",
|
||||
"titleEn": "Recording Costs"
|
||||
},
|
||||
{
|
||||
"slug": "administration",
|
||||
"file": "administration.md",
|
||||
"title": "Administration",
|
||||
"order": 13
|
||||
"order": 13,
|
||||
"fileEn": "administration.en.md",
|
||||
"titleEn": "Administration"
|
||||
},
|
||||
{
|
||||
"slug": "redundanz",
|
||||
"file": "redundanz.md",
|
||||
"title": "Redundanz-Dashboard",
|
||||
"order": 14
|
||||
"order": 14,
|
||||
"fileEn": "redundanz.en.md",
|
||||
"titleEn": "Redundancy dashboard"
|
||||
},
|
||||
{
|
||||
"slug": "papierkorb",
|
||||
"file": "papierkorb.md",
|
||||
"title": "Papierkorb",
|
||||
"order": 15
|
||||
"order": 15,
|
||||
"fileEn": "papierkorb.en.md",
|
||||
"titleEn": "Trash"
|
||||
},
|
||||
{
|
||||
"slug": "tastatur",
|
||||
"file": "tastatur.md",
|
||||
"title": "Tastenkürzel & Kommandopalette",
|
||||
"order": 16
|
||||
"order": 16,
|
||||
"fileEn": "tastatur.en.md",
|
||||
"titleEn": "Keyboard shortcuts & command palette"
|
||||
},
|
||||
{
|
||||
"slug": "datenmodell",
|
||||
"file": "datenmodell.md",
|
||||
"title": "Datenmodell",
|
||||
"order": 17
|
||||
"order": 17,
|
||||
"fileEn": "datenmodell.en.md",
|
||||
"titleEn": "Data model"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,52 @@
|
||||
|
||||
# Login & Account
|
||||
|
||||
## Logging in
|
||||
|
||||
Click **Login** at the bottom left of the sidebar. Depending on the
|
||||
configuration of the instance:
|
||||
|
||||
- **Local accounts:** enter username and password. The accounts are created
|
||||
by an admin (see [Administration](/docs/handbook/administration)).
|
||||
- **OIDC (SSO):** you are redirected to the configured identity provider and
|
||||
log in there.
|
||||
|
||||
The active mode is available at the endpoint
|
||||
[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode).
|
||||
|
||||
> You can reach the login page directly at `/login`. After a successful
|
||||
> login you are redirected back to the page you originally requested.
|
||||
|
||||
## User profile
|
||||
|
||||
You can see your profile (avatar, name, email, plan) at the bottom left in
|
||||
the user menu. There you have the following actions available:
|
||||
|
||||
- **Watchlist** — your saved tools (only with the corresponding plan).
|
||||
- **Trash** — restorable, deleted tools (Premium/Enterprise).
|
||||
- **Change password** — directly in toolr for local accounts; for OIDC
|
||||
accounts, password management is offered in the identity provider.
|
||||
- **Logout** — ends your session.
|
||||
|
||||
## Changing your password (local account)
|
||||
|
||||
1. Open the user menu at the bottom left.
|
||||
2. Select **Change password**.
|
||||
3. Enter the **current** and a **new** password (min. 6 characters) and
|
||||
confirm it.
|
||||
4. Save — the password takes effect immediately.
|
||||
|
||||
API reference: [`POST /auth/me/password`](/docs/reference/endpoints/auth#changeMyPassword).
|
||||
|
||||
## Display settings
|
||||
|
||||
Using the buttons at the top right you can:
|
||||
|
||||
- switch the **language** (German / English),
|
||||
- toggle the **theme** (Light / Dark / System),
|
||||
- adjust the **list view** and **density** in the Browse tools section
|
||||
(see [Finding & browsing tools](/docs/handbook/tools-finden)).
|
||||
|
||||
Your preferences (incl. watchlist) are saved at the endpoint
|
||||
[`GET /auth/me/preferences`](/docs/reference/endpoints/auth#getMePreferences)
|
||||
and updated via [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updateMePreferences).
|
||||
@@ -0,0 +1,35 @@
|
||||
|
||||
# Recording Costs
|
||||
|
||||
On the detail page of a tool you can enter cost and license models so that
|
||||
the total costs per tool become transparent.
|
||||
|
||||
> Costs is a **premium feature** (`costs`, Premium/Enterprise). Admins always
|
||||
> have access.
|
||||
|
||||
## Adding costs
|
||||
|
||||
Click **Add costs** in the costs section of the detail page and fill out the
|
||||
form:
|
||||
|
||||
| Field | Notes |
|
||||
| --- | --- |
|
||||
| **License type** | Free / Subscription / One-Time / Usage-Based |
|
||||
| **Billing period** | Only for "Subscription": Monthly / Quarterly / Annually |
|
||||
| **Costs** | Amount as a number |
|
||||
| **Currency** | EUR / USD / GBP / CHF |
|
||||
| **Notes** | Optional free text |
|
||||
|
||||
Saving creates the entry. Each cost entry is displayed as a card with
|
||||
license badge, billing period, amount (`Amount Currency` or "Free") and
|
||||
notes.
|
||||
|
||||
## Editing & deleting costs
|
||||
|
||||
Hovering over a cost card shows the **Edit** (pencil) and **Delete** (trash)
|
||||
actions.
|
||||
|
||||
## API
|
||||
|
||||
The cost data is managed via the tool endpoints
|
||||
(see [API reference](/docs/reference/endpoints/tools)).
|
||||
@@ -0,0 +1,40 @@
|
||||
|
||||
# Trash
|
||||
|
||||
The **trash** (`/trash`) contains soft-deleted tools. With trash access
|
||||
they can be restored; permanent deletion is reserved for admins.
|
||||
|
||||
> The trash is a **premium feature** (`trash`, Premium/Enterprise).
|
||||
> Admins always have access.
|
||||
|
||||
## Access
|
||||
|
||||
The trash can be reached via the user menu or the sidebar.
|
||||
Without the `trash` permission, a hint about changing the plan appears.
|
||||
|
||||
## Restoring
|
||||
|
||||
- Select one or more tools (checkboxes).
|
||||
- Click on **Restore (N)** — the tools appear again in all
|
||||
public views.
|
||||
|
||||
> Restoring is available to anyone with trash access.
|
||||
|
||||
## Permanently delete (admin only)
|
||||
|
||||
- **Delete (N)** **permanently** removes the selected tools — including
|
||||
all ratings, costs and links. This cannot be undone.
|
||||
- **Empty trash** permanently removes all soft-deleted tools.
|
||||
|
||||
## Table
|
||||
|
||||
The trash lists: name, category, **Deleted on** (`tt.MM.jjjj HH:mm`),
|
||||
**Deleted by** as well as actions (Restore; Delete admin only). The search
|
||||
filters by name.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /tools/trash`](/docs/reference/endpoints/tools#listTrashedTools) — list
|
||||
- [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoreTools) — restore
|
||||
- [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deleteTrashedTools) — permanently delete (admin)
|
||||
- [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptyTrash) — empty trash (admin)
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# Plans & Permissions
|
||||
|
||||
toolr distinguishes **plans** (tier) and **roles**. Admins bypass all feature
|
||||
restrictions.
|
||||
|
||||
## Plans
|
||||
|
||||
| Plan | Description |
|
||||
| --- | --- |
|
||||
| **Free** | Basic functions: search, filter, view, analytics |
|
||||
| **Premium** | Additionally watchlist, compare, trash, costs |
|
||||
| **Enterprise** | All premium features + extended support |
|
||||
|
||||
### Feature permissions
|
||||
|
||||
Premium/Enterprise unlock the following features:
|
||||
|
||||
| Feature | Function | Learn more |
|
||||
| --- | --- | --- |
|
||||
| `compare` | Compare tools | [Compare](/docs/handbook/vergleichen) |
|
||||
| `watchlist` | Favorites list | [Watchlist](/docs/handbook/watchlist) |
|
||||
| `trash` | Trash (soft-deleted tools) | [Trash](/docs/handbook/papierkorb) |
|
||||
| `costs` | Record cost/license models | [Recording costs](/docs/handbook/kosten) |
|
||||
|
||||
If you are missing a feature, the app shows an **upgrade notice** with a link
|
||||
to the plan management.
|
||||
|
||||
## Roles
|
||||
|
||||
| Role | Permissions |
|
||||
| --- | --- |
|
||||
| **User** | Standard account: create/rate tools, edit your own tools |
|
||||
| **Admin** | All user rights + administration, audit log, redundancy, empty trash, tool links |
|
||||
|
||||
Admins pass **all** feature checks — even without a premium plan.
|
||||
|
||||
## Plan/role management
|
||||
|
||||
The assignment of role and plan is managed by admins in the
|
||||
[Administration](/docs/handbook/administration) section (tab "Users").
|
||||
@@ -0,0 +1,38 @@
|
||||
|
||||
# Redundancy dashboard
|
||||
|
||||
The **Redundancy dashboard** (`/admin/redundancy`) is an admin tool for
|
||||
automatic detection of duplicate or strongly overlapping tools — per
|
||||
category — including cost and rating comparison.
|
||||
|
||||
> Access is reserved exclusively for admins (the API is
|
||||
> admin-protected).
|
||||
|
||||
## Layout
|
||||
|
||||
- **Per category** a group is shown: name of the category,
|
||||
number of tools and comparisons as well as the **total monthly costs**
|
||||
if applicable (e.g. `€X.XX/mo total`).
|
||||
- Each tool is displayed as a card: name, monthly costs, number of
|
||||
ratings, combined rating, license badges and number of features.
|
||||
|
||||
## Comparisons & recommendations
|
||||
|
||||
For each tool pair the following appears:
|
||||
|
||||
- Tool A vs. Tool B, each with rating (`X.X ★`) and monthly costs.
|
||||
- **Overlap** in percent (progress bar in the middle).
|
||||
- A **recommendation** with confidence color:
|
||||
- **high** (green), **medium** (yellow), **low** (gray)
|
||||
- The recommended, better tool is marked with a "thumbs up" and justified.
|
||||
|
||||
## Manual rating
|
||||
|
||||
You can rate a pair manually: click on Tool A or Tool B to
|
||||
record which one is better. The selection is saved and the
|
||||
display is updated.
|
||||
|
||||
## API
|
||||
|
||||
- [`GET /api/admin/redundancy`](#) — load data (admin-protected)
|
||||
- [`POST /api/admin/redundancy/evaluate`](#) — save manual rating
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
# Keyboard shortcuts & command palette
|
||||
|
||||
## Command palette
|
||||
|
||||
The command palette is the central quick navigation:
|
||||
|
||||
- Open with **`⌘K`** (macOS) or **`Ctrl+K`** (Windows/Linux).
|
||||
- Alternatively via the search bar at the top right ("Search tools… ⌘K") or the
|
||||
search icon on mobile devices.
|
||||
|
||||
### Empty state
|
||||
|
||||
Without input, the palette shows:
|
||||
|
||||
- **Recently viewed** — the last 5 tools you visited.
|
||||
- **Navigation** — browse tools, add tool, analytics as well as
|
||||
(depending on permissions) watchlist, trash and admin.
|
||||
|
||||
### Search
|
||||
|
||||
Type to search for tools live (max. 10 results, incl. rating
|
||||
`X.X★`).
|
||||
|
||||
## Overview of keyboard shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| `⌘K` / `Ctrl+K` | Open command palette |
|
||||
| `/` | Focus search in the "Browse tools" area |
|
||||
|
||||
## Additional notes
|
||||
|
||||
- **Recently viewed** is stored locally in the browser (max. 5 entries).
|
||||
- The sidebar (left navigation) can be collapsed on desktop; the
|
||||
breadcrumb at the top shows your current location.
|
||||
@@ -0,0 +1,46 @@
|
||||
|
||||
# Create a tool
|
||||
|
||||
To add a new tool to the catalog, click **Add tool**
|
||||
(`/tools/new`). Creating a tool requires an account — without being signed in
|
||||
a notice with a login button appears.
|
||||
|
||||
## Form fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Name** | Yes | At least 2 characters |
|
||||
| **Category** | Yes | Dropdown; new categories can be created directly |
|
||||
| **Website URL** | No | Valid URL (e.g. `https://...`) |
|
||||
| **Icon / Logo URL** | No | Valid URL; preview is shown live |
|
||||
| **Description** | Yes | At least 10 characters; describe what the tool does |
|
||||
| **Features** | No | Dynamic list with autocomplete (max. 6) |
|
||||
| **Tags** | No | Dynamic list with autocomplete |
|
||||
|
||||
Next to each field, the **? icon** takes you directly to the corresponding
|
||||
field description in the [data model reference](/docs/reference/schemas/toolinput).
|
||||
|
||||
### Category
|
||||
|
||||
- Type to search for existing categories.
|
||||
- Select **+ Create "..."** to create a new category.
|
||||
|
||||
### Features & tags
|
||||
|
||||
- **Add feature** / **Add tag** appends a new row.
|
||||
- The input fields suggest existing features/tags
|
||||
(autocomplete, max. 6 suggestions).
|
||||
- Use the **×** button to remove individual rows.
|
||||
- Features and tags help with filtering and finding tools again.
|
||||
|
||||
## Save
|
||||
|
||||
Click **Add tool**. After successful creation you will be redirected to the
|
||||
detail page of the new tool.
|
||||
|
||||
## API
|
||||
|
||||
- [`POST /tools`](/docs/reference/endpoints/tools#createTool) — create a tool
|
||||
- [`GET /categories`](/docs/reference/endpoints/tools#listCategories) — categories
|
||||
- [`GET /features/all`](/docs/reference/endpoints/tools#listAllFeatures) — features
|
||||
- [`GET /tags/all`](/docs/reference/endpoints/tools#listAllTags) — tags
|
||||
@@ -0,0 +1,32 @@
|
||||
|
||||
# Edit & delete tools
|
||||
|
||||
## Editing
|
||||
|
||||
On the detail page of a tool you will find the **Edit** button
|
||||
(only for the person who created the tool, as well as for admins).
|
||||
|
||||
The edit page (`/tools/:id/edit`) contains the same fields as when
|
||||
creating (name, category, website/icon URL, description, features, tags) —
|
||||
already filled with the current values.
|
||||
|
||||
- **Save** applies the changes.
|
||||
- **Cancel** takes you back to the detail page.
|
||||
|
||||
API reference: [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updateTool).
|
||||
|
||||
## Deleting
|
||||
|
||||
Via **Delete** on the detail page the tool is removed. The behavior
|
||||
depends on your plan:
|
||||
|
||||
- **With trash access** (Premium/Enterprise or Admin): the tool is
|
||||
**soft deleted** — it disappears from all public views, but can
|
||||
be restored or permanently deleted in the [trash](/docs/handbook/papierkorb).
|
||||
- **Without trash access:** the tool is **permanently** deleted and cannot
|
||||
be restored.
|
||||
|
||||
Deletion is only possible for the person who created the tool, as well as
|
||||
for admins.
|
||||
|
||||
API reference: [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deleteTool).
|
||||
@@ -0,0 +1,66 @@
|
||||
|
||||
# Find & browse tools
|
||||
|
||||
The **Browse tools** section (`/tools`) is your entry point to the catalog.
|
||||
Here you combine search, filters and sorting to find exactly the tools
|
||||
you are interested in.
|
||||
|
||||
## Search
|
||||
|
||||
- The **search bar** searches name and description (full text).
|
||||
- Shortcut: Press **`/`** to focus the search.
|
||||
- The input is debounced so that filtering happens immediately with each
|
||||
keystroke.
|
||||
|
||||
## Filter
|
||||
|
||||
Via the **Filter** button (with a badge for the number of active filters)
|
||||
you open the filter popover with:
|
||||
|
||||
- **Tags** — selection via checkboxes (scrollable list).
|
||||
- **Features** — selection via checkboxes.
|
||||
- **Minimum rating** — slider from 0 to 5 (in steps of 0.5); shows
|
||||
e.g. "3.0+".
|
||||
|
||||
Active filters appear as **removable chips** above the result list.
|
||||
Use **Reset filters** or **Remove all** to clear them again.
|
||||
|
||||
## Sort
|
||||
|
||||
The **Sort** dropdown offers the following options:
|
||||
|
||||
| Sort | Description |
|
||||
| --- | --- |
|
||||
| Newest | New tools first |
|
||||
| Top rated | By combined rating |
|
||||
| Most rated | By number of ratings |
|
||||
| Name (A–Z) | Alphabetically ascending |
|
||||
| Name (Z–A) | Alphabetically descending |
|
||||
| Last updated | By last update |
|
||||
|
||||
## View & density
|
||||
|
||||
- **Switch view:** grid / table / rows.
|
||||
- **Density:** comfortable / compact (slider).
|
||||
|
||||
Your selection is saved — locally in the browser and, for logged-in users,
|
||||
additionally on the server in the preferences. View, density, search, filters
|
||||
and sorting are reflected in the URL so you can share results.
|
||||
|
||||
## Table view
|
||||
|
||||
In the table view the columns **Tool**, **Rating** and **Number of
|
||||
ratings** are sortable. Hovering over a row shows a preview
|
||||
with rating details, tags and mini bars.
|
||||
|
||||
## Selecting for comparison & watchlist
|
||||
|
||||
- On every card/row you find a **compare icon** that lets you add tools to the
|
||||
[compare bar](/docs/handbook/vergleichen).
|
||||
- The **bookmark icon** saves tools to your
|
||||
[watchlist](/docs/handbook/watchlist) (only with the corresponding plan).
|
||||
|
||||
## API
|
||||
|
||||
All search, filter and sort parameters correspond to the query parameters of
|
||||
[`GET /tools`](/docs/reference/endpoints/tools#listTools).
|
||||
@@ -0,0 +1,42 @@
|
||||
|
||||
# Compare
|
||||
|
||||
With the compare function you can put several tools **side by side** —
|
||||
ideal for making a well-informed decision.
|
||||
|
||||
> Comparing is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Selecting tools
|
||||
|
||||
1. In the **Browse tools** section, click the **compare icon** (scales) on
|
||||
each card/row.
|
||||
2. The **compare bar** appears at the bottom with the selected tools as
|
||||
chips. You can remove individual tools (×) or clear the selection.
|
||||
3. Click **Compare (N)** to go to the compare view.
|
||||
|
||||
> Without a premium plan the button is locked (lock icon). The dialog takes
|
||||
> you to the plan switch
|
||||
> (see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## The compare view
|
||||
|
||||
The view shows a table with one column per tool. Rows:
|
||||
|
||||
| Row | Content |
|
||||
| --- | --- |
|
||||
| **Rating** | Stars + value (e.g. `4.2/5`) |
|
||||
| **Usefulness** | Value (X.X/5) |
|
||||
| **Usability** | Value (X.X/5) |
|
||||
| **Number of ratings** | Count |
|
||||
| **Description** | Text |
|
||||
| **Features** | Badges |
|
||||
| **Tags** | Badges |
|
||||
| **Last updated** | Date |
|
||||
|
||||
The **best value** per row is highlighted (with trophy icon).
|
||||
|
||||
## API
|
||||
|
||||
The compare view reads the data via
|
||||
[`GET /compare`](/docs/reference/endpoints/tools#listCompareTools).
|
||||
@@ -0,0 +1,33 @@
|
||||
|
||||
# Watchlist
|
||||
|
||||
The **watchlist** is a personal favorites list. You can open and compare the
|
||||
tools in it at any time with a click.
|
||||
|
||||
> The watchlist is a **premium feature** (Premium/Enterprise) and is always
|
||||
> available to admins.
|
||||
|
||||
## Prerequisite
|
||||
|
||||
You need a plan with the `watchlist` permission. If it is missing, a note
|
||||
about switching plans appears at the bookmark
|
||||
(see [Plans & permissions](/docs/handbook/plaene)).
|
||||
|
||||
## Saving a tool
|
||||
|
||||
- On every card/row in the **Browse tools** section you will find the
|
||||
**bookmark icon**.
|
||||
- A click saves the tool to your watchlist — the icon becomes filled.
|
||||
- Clicking it again removes it.
|
||||
|
||||
## Viewing the watchlist
|
||||
|
||||
Open the watchlist via the user menu or the sidebar. It shows all saved tools
|
||||
as cards. The filled bookmark on a card removes the tool from the list.
|
||||
|
||||
## Where is the watchlist stored?
|
||||
|
||||
The watchlist is a list of tool IDs in your **user preferences**. This way it
|
||||
is linked to your account across devices.
|
||||
|
||||
API reference: [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getMeWatchlist).
|
||||
@@ -0,0 +1,49 @@
|
||||
# v0.8.3 — Release Notes
|
||||
|
||||
**Date:** 2026-08-04 · **Tag:** [`v0.8.3`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.3)
|
||||
|
||||
## New features
|
||||
|
||||
- **Version-based documentation**: Each release now carries a
|
||||
complete docs snapshot (manual + API reference). Via the
|
||||
version dropdown you can reach the docs of the respective version
|
||||
(`/docs/vX.Y.Z/…`) — including the manual and reference as they
|
||||
applied at release time. The last 7 versions remain available.
|
||||
- **Help buttons in forms (NetBox style)**: For evaluation, tool
|
||||
create/edit, costs, comparing, watchlist and analytics there is now
|
||||
a help icon that leads directly to the matching guide in the manual.
|
||||
|
||||
## Fixes & improvements
|
||||
|
||||
- **Gitea tag links fixed**: `…/tags/vX.Y.Z` was a 404 page; the
|
||||
correct URL is `/releases/tag/vX.Y.Z` (in all release notes and the
|
||||
docs page).
|
||||
- Version switching now leads to the docs of the selected version instead of
|
||||
just the release page; old `/docs/vX.Y.Z` redirects are removed.
|
||||
- Docs generator: `--snapshot` creates manual + reference per version; on
|
||||
build, the snapshots of the last 7 versions are included.
|
||||
|
||||
## API changes
|
||||
|
||||
- No changes to the API.
|
||||
|
||||
## Operations / upgrade
|
||||
|
||||
- **Env vars:** unchanged.
|
||||
- **Migration:** none.
|
||||
- **Breaking changes:** none. New release notes must use the correct
|
||||
tag link (see `docs/releases/TEMPLATE.md`). For versions before
|
||||
this release, snapshots can be created retroactively:
|
||||
`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- Older releases without a snapshot (e.g. v0.6.0) only show their release notes,
|
||||
no manual/reference. Backfill with `--snapshot`.
|
||||
- The docs version corresponds to the state of the docs at the time the
|
||||
snapshot was created; manual changes apply from the respective next release.
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`3bb4598`](https://git.kubebase.de/admin/tool-evaluator/commit/3bb4598)
|
||||
- Tag: [`v0.8.3`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.3)
|
||||
Reference in New Issue
Block a user