dereuromark · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/README.md b/README.md
@@ -8,40 +8,10 @@
 [![Total Downloads](https://poser.pugx.org/dereuromark/cakephp-queue/d/total)](https://packagist.org/packages/dereuromark/cakephp-queue)
 [![Coding Standards](https://img.shields.io/badge/cs-PSR--2--R-purple.svg?style=flat-square)](https://github.com/php-fig-rectified/fig-rectified-standards)
 
-This branch is for use with **CakePHP 5.1+**. For details see [version map](https://github.com/dereuromark/cakephp-queue/wiki#cakephp-version-map).
 
+Queue stores background jobs in your application's database and processes them with CLI workers. Tasks support retries, delayed execution, progress, and optional admin tools.
 
-## Background
-
-This is a very simple and minimalistic job queue (or deferred-task) system for CakePHP.
-If you need a very basic PHP internal queue tool, this is definitely an option.
-It is also a great tool for demo purposes on how queues work and doesn't have any dependencies.
-
-Overall functionality is inspired by systems like Gearman, Beanstalk or dropr, but without
-any illusion to compete with these more advanced Systems.
-
-The plugin is an attempt to provide a basic, simple to use method to enable deferred job execution,
-without the hassle of setting up or running an extra queue daemon, while integrating nicely into
-CakePHP and also simplifying the creation of worker scripts. You can also easily provide progress and status information into your pages.
-
-Please also read my blog posts about [deferred execution](https://www.dereuromark.de/2013/12/22/queue-deferred-execution-in-cakephp/) and [real-life example usage](https://www.dereuromark.de/2021/07/15/cakephp-queuing-real-life-examples/) [new].
-For more high-volume and sophisticated use cases please see the [awesome list](https://github.com/FriendsOfCake/awesome-cakephp#queue) alternatives.
-
-### Why use deferred execution?
-
-Deferred execution makes sense (especially in PHP) when your page wants to execute tasks, which are not directly related to rendering the current page.
-For instance, in a BBS-type system, a new users post might require the creation of multiple personalized email messages,
-notifying other users of the new content.
-Creating and sending these emails is completely irrelevant to the currently active user, and should not increase page response time.
-Another example would be downloading, extraction and/or analyzing an external file per request of the user.
-The regular solution to these problems would be to create specialized cronjobs which use specific database states to determine which action should be done.
-
-The Queue plugin provides a simple method to create and run such non-user-interaction-critical tasks.
-
-Another important reason is that specific jobs can be (auto)retried if they failed.
-So if the email server didn't work the first time, or the API gateway had an issue, the current job to be executed isn't lost but kept for rerun. Most of those external services should be treated as failable once every x calls, and as such a queue implementation can help reducing issues due to such failures. If a job still can't finish despite retries, you still have the option to debug its payload and why this job cannot complete. No data is lost here.
-
-While you can run multiple workers, and can (to some extent) spread these workers to different machines via a shared database, you should consider using a more advanced system for high volume/high number of workers systems.
+See the [documentation](https://dereuromark.github.io/cakephp-queue/) for [installation](https://dereuromark.github.io/cakephp-queue/guide/installation), [getting started](https://dereuromark.github.io/cakephp-queue/guide/getting-started), and the full reference.
 
 ## Demo
 See [Sandbox app](https://sandbox.dereuromark.de/sandbox/queue-examples).
@@ -50,4 +20,4 @@ See [Sandbox app](https://sandbox.dereuromark.de/sandbox/queue-examples).
 Full documentation: https://dereuromark.github.io/cakephp-queue/
 
 ## Cronjob based background scheduling
-If you are looking for scheduling certain background jobs: This plugin works flawlessly with [QueueScheduler plugin](https://github.com/dereuromark/cakephp-queue-scheduler).
+If you are looking for scheduling certain background jobs: Use [QueueScheduler plugin](https://github.com/dereuromark/cakephp-queue-scheduler).
diff --git a/config/app.example.php b/config/app.example.php
@@ -74,13 +74,13 @@
 		// set default datasource connection
 		'connection' => null,
 
-		// Multi-connection mode: whitelist of datasource connection names a
-		// worker / job command may run against. Leave empty (or with fewer than
-		// 2 entries) to stay in single-connection mode, where the singular
-		// `connection` above (or 'default') is used. With 2+ entries, the first
-		// is the default and any --connection passed to the run/job commands
-		// must appear in this list or a RuntimeException is thrown. The admin
-		// dashboard also exposes a connection switcher when this has 2+ entries.
+		// Multi-connection mode: allowed datasource names for add, run, job,
+		// info and worker commands. With 2+ entries, the first is the default;
+		// an explicit --connection must appear in this list.
+		// With fewer than 2 entries, commands preserve the QueuedJobs table's
+		// assigned connection, whose default comes from `connection` above
+		// or 'default'. An explicit --connection overrides that choice.
+		// The admin dashboard exposes a switcher with 2+ entries.
 		'connections' => [
 			//'default',
 			//'queue_secondary',

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -6,7 +6,8 @@ function guideSidebar() {
       text: 'Guide',
       items: [
         { text: 'Overview', link: '/guide/' },
-        { text: 'Basic Setup', link: '/guide/basic-setup' },
+        { text: 'Installation', link: '/guide/installation' },
+        { text: 'Getting started', link: '/guide/getting-started' },
         { text: 'Queueing Jobs', link: '/guide/queueing-jobs' },
         { text: 'Custom Tasks', link: '/guide/custom-tasks' },
       ],
@@ -52,6 +53,8 @@ export default defineConfig({
   themeConfig: {
     logo: '/logo.svg',
     nav: [
+      { text: 'Installation', link: '/guide/installation' },
+      { text: 'Getting started', link: '/guide/getting-started' },
       { text: 'Guide', link: '/guide/', activeMatch: '/(guide|admin)/' },
       { text: 'Tasks', link: '/tasks/', activeMatch: '/tasks/' },
       { text: 'Reference', link: '/reference/', activeMatch: '/reference/' },

diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -1,7 +1,7 @@
 :root {
   --vp-c-brand-1: #0f766e;
   --vp-c-brand-2: #14b8a6;
-  --vp-c-brand-3: #5eead4;
+  --vp-c-brand-3: #0f766e;
   --vp-c-brand-soft: rgba(20, 184, 166, 0.14);
 
   --vp-home-hero-name-color: transparent;
@@ -13,7 +13,7 @@
 .dark {
   --vp-c-brand-1: #5eead4;
   --vp-c-brand-2: #2dd4bf;
-  --vp-c-brand-3: #14b8a6;
+  --vp-c-brand-3: #0f766e;
 }
 
 .vp-doc table code,

diff --git a/docs/admin/index.md b/docs/admin/index.md
@@ -2,7 +2,7 @@
 
 The Queue plugin includes a modern, self-contained admin dashboard for managing your queued jobs. The dashboard is completely isolated from your application's CSS/JS, using Bootstrap 5 and Font Awesome 6 via CDN.
 
-## Features
+## Available actions
 
 - **Statistics Overview**: Real-time counts of pending, scheduled, running, and failed jobs
 - **Status Banner**: Visual indicator showing whether the queue is running or idle
@@ -55,36 +55,28 @@ This is useful when:
 
 ### Authorization (`Queue.adminAccess`, required)
 
-The admin UI can trigger jobs (via `AddFromBackendInterface` tasks),
-reset/remove queued jobs, and terminate workers — operational damage if
-exposed. The plugin therefore **fails closed by default**: every request
-to `/admin/queue/...` is rejected with `403` until the host app
-explicitly configures access.
+Set `Queue.adminAccess` to a `Closure` that receives the current request and returns `true` to grant access. Requests reaching this gate without a configured closure are denied with 403. The host controller's redirects take precedence in the default inherited mode.
 
-Set `Queue.adminAccess` to a `Closure` that receives the current request
-and returns literal `true` to grant access. Anything else (unset,
-non-`Closure`, returns `false`, returns a truthy non-bool, throws)
-yields a `403`.
+The gate protects job creation, resetting and deleting jobs, and worker management. It runs in both inherited and standalone modes.
 
 ```php
 use Cake\Core\Configure;
 use Cake\Http\ServerRequest;
 
-// Example — admin role check (cakephp/authentication identity):
+// Example: admin role check (cakephp/authentication identity):
 Configure::write('Queue.adminAccess', function (ServerRequest $request): bool {
     $identity = $request->getAttribute('identity');
     return $identity !== null && in_array('admin', (array)$identity->roles, true);
 });
 ```
 
 The gate runs in `beforeFilter` for every admin controller in the plugin
-and plays nicely with the cakephp/authorization plugin (it calls
-`skipAuthorization()` so the policy layer doesn't double-reject).
+and calls `skipAuthorization()` when an authorization service is present.
 `ForbiddenException` raised inside the Closure is respected as-is so
 callers can short-circuit with their own message; other throwables are
 logged via `Cake\Log\Log` and converted to a generic `403`.
 
-`Queue.adminAccess` is independent of `Queue.standalone` — the access
+`Queue.adminAccess` is independent of `Queue.standalone`; the access
 gate runs in both modes.
 
 ### Using Your Application's Layout

diff --git a/docs/guide/basic-setup.md b/docs/guide/basic-setup.md
@@ -1,27 +1,3 @@
-# Basic Setup
+# Basic setup
 
-## Installation
-```
-composer require dereuromark/cakephp-queue
-```
-Load the plugin
-```
-bin/cake plugin load Queue
-```
-
-If you don't want to also access the backend controller (just using CLI), you need to use
-```
-bin/cake plugin load Queue --no-routes
-```
-
-Important: Make sure to use authentication if you are using the backend. You do not want visitors to be able to browse it.
-
-## Database migration
-
-Run the following command in the CakePHP console to create the tables using the Migrations plugin:
-```sh
-bin/cake migrations migrate -p Queue
-```
-
-Hint: use a native *nix-like or console and not the one provided like from Git (git-bash). This may lead to a non-working `migrations` command.
-It is also advised to have the `posix` PHP extension enabled.
+Setup is covered in [Installation](./installation). To queue and run your first job, follow [Getting started](./getting-started).