diff --git a/docs/content/docs/java/api-reference/queue.mdx b/docs/content/docs/java/api-reference/queue.mdx
deleted file mode 100644
index b0a5fde6..00000000
--- a/docs/content/docs/java/api-reference/queue.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: Taskito
-description: "Construct the client and the full producer/admin API."
----
-
-```java
-import org.byteveda.taskito.Taskito;
-
-try (Taskito taskito = Taskito.builder().sqlite("taskito.db").open()) {
-    // ...
-}
-```
-
-`Taskito` is `AutoCloseable`; `close()` releases the native storage handle.
-
-## Builder
-
-| Method | Description |
-|---|---|
-| `backend(String)` | `"sqlite"` (default) \| `"postgres"` \| `"redis"`. |
-| `url(String)` | Connection string: a file path for SQLite, a URL for Postgres/Redis. |
-| `sqlite()` / `sqlite(path)` / `postgres(url)` / `redis(url)` | Backend shortcuts. SQLite defaults to `.taskito/taskito.db`. |
-| `poolSize(int)` | Connection pool size (SQLite/Postgres). |
-| `schema(String)` | Postgres schema (default `taskito`). |
-| `prefix(String)` | Redis key prefix. |
-| `namespace(String)` | Namespace applied to enqueued jobs + the worker scheduler. |
-| `serializer(Serializer)` | Payload/result serializer (default `JsonSerializer`). |
-| `codec(PayloadCodec...)` | Global [codec chain](/java/api-reference/serializers) around the serializer. |
-| `codec(String, PayloadCodec)` | Register a named codec for per-task selection (`Task.codecs`). |
-| `open()` | Open the native backend → `Taskito`. |
-| `open(QueueBackend)` | Open over an explicit backend (e.g. a test fake). |
-
-## Producer
-
-| Method | Description |
-|---|---|
-| `enqueue(Task<T>, T)` / `enqueue(Task<T>, T, EnqueueOptions)` | Enqueue a typed payload → job id. |
-| `enqueue(String taskName, Object payload)` | Enqueue by task name. |
-| `tryEnqueue(...)` | Gate-aware `enqueue`: `Optional.empty()` when a gate skips; a `Reject` still throws. |
-| `enqueueMany(Task<T>, List<T>)` / `(..., EnqueueOptions)` | Batch-enqueue in one storage call → ids in input order (no dedup). |
-| `enqueueAll(Task<T>, List<T>)` | Alias of `enqueueMany`. |
-
-## Results & cancellation
-
-| Method | Description |
-|---|---|
-| `getJob(id)` → `Optional<Job>` | A job snapshot (status, progress, timestamps). |
-| `awaitJob(id, Duration)` → `Optional<Job>` | Block until terminal; throws on timeout. |
-| `getResult(id)` → `Optional<byte[]>` / `getResult(id, Class<R>)` → `Optional<R>` | The job's result, raw or [deserialized](/java/api-reference/result). |
-| `cancel(id)` | Cancel a pending job. |
-| `requestCancel(id)` / `isCancelRequested(id)` | Cooperative cancellation of a running job. |
-| `setProgress(id, int)` | Record 0–100 progress for inspection / the dashboard. |
-
-## Inspection
-
-| Method | Description |
-|---|---|
-| `stats()` / `statsByQueue(q)` / `statsAllQueues()` | `QueueStats` counts by status. |
-| `listJobs(JobFilter)` | List jobs — filter by status/queue/task with limit/offset. |
-| `jobErrors(id)` → `List<JobError>` | Per-attempt error history. |
-| `metrics(taskName, sinceMs)` → `List<TaskMetric>` | Per-execution metrics (null task = all). |
-| `listWorkers()` → `List<WorkerInfo>` | Registered workers (heartbeat + identity). |
-| `writeTaskLog(...)` / `getTaskLogs(id)` | Structured task-log lines for a job. |
-
-## Admin
-
-| Method | Description |
-|---|---|
-| `listDead(limit, offset)` / `listDeadByTask(task, limit, offset)` | Dead-letter entries. |
-| `retryDead(deadId)` (alias `retry`) / `deleteDead(deadId)` | Re-enqueue / drop an entry. |
-| `purgeDead(olderThanMs)` / `purgeDeadByTask(task)` | Bulk DLQ cleanup → count removed. |
-| `purgeCompleted(olderThanMs)` | Drop old completed jobs. |
-| `queue(name)` → `Queue` | A named-queue handle: `name()`, `pause()`, `resume()`, `isPaused()`. |
-| `listPausedQueues()` | Names of every paused queue. |
-| `getSetting` / `setSetting` / `deleteSetting` / `listSettings` | Shared key–value settings in the store. |
-
-## Locks & periodic
-
-| Method | Description |
-|---|---|
-| `lock(name, ttlMs)` / `lock(name)` | A distributed `Lock` (default 30s TTL): `acquire()`, `tryAcquire(timeout)`, `extend(ttlMs)`, `close()`. |
-| `withLock(name, ttlMs, Runnable)` | Acquire → run → release; returns whether it ran. |
-| `lockInfo(name)` (alias `getLockInfo`) | Current holder metadata, if held. |
-| `registerPeriodic(PeriodicTask)` | Register (or replace) a cron task → next fire time (Unix ms). |
-| `listPeriodic()` / `deletePeriodic(name)` / `pausePeriodic(name)` / `resumePeriodic(name)` | Periodic task management. |
-
-## Pub/Sub
-
-See [Pub/Sub](/java/guides/core/pubsub) for the full guide (delivery
-semantics, lifecycle, cross-SDK topics).
-
-| Method | Description |
-|---|---|
-| `subscribe(topic, Task<T>)` / `subscribe(topic, Task<T>, SubscriptionOptions)` | Wire `Task` into `topic`'s routing (durable by default). Register the handler on the worker separately, as for any task. |
-| `publish(topic, payload)` / `publish(topic, payload, PublishOptions)` → `List<Job>` | Fan a message out to every active subscription — one job each. Empty list when nothing is subscribed. |
-| `unsubscribe(topic, name)` | Remove a subscription; `false` if none matched. |
-| `pauseSubscription(topic, name)` / `resumeSubscription(topic, name)` | Stop/resume deliveries without unregistering; `false` if none matched. |
-| `listSubscriptions()` / `listSubscriptions(topic)` | Every subscription, or one topic's active ones. |
-| `listTopics()` | Distinct topics with at least one subscription. |
-
-## Subsystems
-
-| Method | Description |
-|---|---|
-| `worker()` → `Worker.Builder` | Begin building a [worker](/java/api-reference/worker). |
-| `use(Middleware)` | Cross-cutting hooks — `onEnqueue`, `before`/`after`/`onError`, and the outcome hooks. |
-| `resource(...)` | Register an injectable [resource](/java/api-reference/resources). |
-| `predicate(taskName, Predicate)` / `gate(taskName, EnqueueGate)` | Enqueue-time gates: reject, skip, or defer submissions. |
-| `intercept(Interceptor)` | Pass / convert / redirect / reject each enqueue before serialization. |
-| `submitWorkflow(Workflow)` / `submitWorkflow(Workflow, Map)` | Submit a [workflow](/java/api-reference/workflows) → `WorkflowRun`. |
-| `workflowStatus(runId)` / `cancelWorkflow(runId)` | Run queries and cancellation. |
-| `resourceMetrics()` | Per-resource created/disposed/active counters. |
-
-`WebhookManager.attach(taskito)` registers outcome webhooks, and
-`Scaler.start(taskito, ScalerOptions.onPort(9090))` serves a queue-depth
-endpoint for external autoscalers — both build on this client.
diff --git a/docs/content/docs/java/api-reference/queue/events.mdx b/docs/content/docs/java/api-reference/queue/events.mdx
new file mode 100644
index 00000000..b81d61ae
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/events.mdx
@@ -0,0 +1,16 @@
+---
+title: Events & Logs
+description: "Structured task logs, webhooks, and the autoscaler."
+---
+
+## Logs
+
+| Method | Description |
+|---|---|
+| `writeTaskLog(...)` / `getTaskLogs(id)` | Structured task-log lines for a job. |
+
+## Webhooks & autoscaler
+
+`WebhookManager.attach(taskito)` registers outcome webhooks, and
+`Scaler.start(taskito, ScalerOptions.onPort(9090))` serves a queue-depth
+endpoint for external autoscalers — both build on this client.
diff --git a/docs/content/docs/java/api-reference/queue/index.mdx b/docs/content/docs/java/api-reference/queue/index.mdx
new file mode 100644
index 00000000..3d95442b
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/index.mdx
@@ -0,0 +1,54 @@
+---
+title: Taskito
+description: "Construct the client and the full producer/admin API."
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+```java
+import org.byteveda.taskito.Taskito;
+
+try (Taskito taskito = Taskito.builder().sqlite("taskito.db").open()) {
+    // ...
+}
+```
+
+`Taskito` is `AutoCloseable`; `close()` releases the native storage handle.
+
+<Callout type="info" title="Sub-pages">
+  The `Taskito` API is split across several pages for readability:
+
+  - **[Job Management](/java/api-reference/queue/jobs)** — results, cancellation, listing, error history
+  - **[Queue & Stats](/java/api-reference/queue/queues)** — statistics, dead letters, queue control, settings
+  - **[Workers & Hooks](/java/api-reference/queue/workers)** — worker builder, middleware, workflow control
+  - **[Resources & Locking](/java/api-reference/queue/resources)** — resources, enqueue gates, distributed locks, periodic tasks
+  - **[Events & Logs](/java/api-reference/queue/events)** — structured task logs, webhooks, autoscaler
+  - **[Pub/Sub](/java/api-reference/queue/pubsub)** — topic subscriptions, fan-out publish
+</Callout>
+
+## Builder
+
+| Method | Description |
+|---|---|
+| `backend(String)` | `"sqlite"` (default) \| `"postgres"` \| `"redis"`. |
+| `url(String)` | Connection string: a file path for SQLite, a URL for Postgres/Redis. |
+| `sqlite()` / `sqlite(path)` / `postgres(url)` / `redis(url)` | Backend shortcuts. SQLite defaults to `.taskito/taskito.db`. |
+| `poolSize(int)` | Connection pool size (SQLite/Postgres). |
+| `schema(String)` | Postgres schema (default `taskito`). |
+| `prefix(String)` | Redis key prefix. |
+| `namespace(String)` | Namespace applied to enqueued jobs + the worker scheduler. |
+| `serializer(Serializer)` | Payload/result serializer (default `JsonSerializer`). |
+| `codec(PayloadCodec...)` | Global [codec chain](/java/api-reference/serializers) around the serializer. |
+| `codec(String, PayloadCodec)` | Register a named codec for per-task selection (`Task.codecs`). |
+| `open()` | Open the native backend → `Taskito`. |
+| `open(QueueBackend)` | Open over an explicit backend (e.g. a test fake). |
+
+## Producer
+
+| Method | Description |
+|---|---|
+| `enqueue(Task<T>, T)` / `enqueue(Task<T>, T, EnqueueOptions)` | Enqueue a typed payload → job id. |
+| `enqueue(String taskName, Object payload)` | Enqueue by task name. |
+| `tryEnqueue(...)` | Gate-aware `enqueue`: `Optional.empty()` when a gate skips; a `Reject` still throws. |
+| `enqueueMany(Task<T>, List<T>)` / `(..., EnqueueOptions)` | Batch-enqueue in one storage call → ids in input order (no dedup). |
+| `enqueueAll(Task<T>, List<T>)` | Alias of `enqueueMany`. |
diff --git a/docs/content/docs/java/api-reference/queue/jobs.mdx b/docs/content/docs/java/api-reference/queue/jobs.mdx
new file mode 100644
index 00000000..a70538f0
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/jobs.mdx
@@ -0,0 +1,22 @@
+---
+title: Job Management
+description: "Job results, cancellation, listing, and error history."
+---
+
+## Results & cancellation
+
+| Method | Description |
+|---|---|
+| `getJob(id)` → `Optional<Job>` | A job snapshot (status, progress, timestamps). |
+| `awaitJob(id, Duration)` → `Optional<Job>` | Block until terminal; throws on timeout. |
+| `getResult(id)` → `Optional<byte[]>` / `getResult(id, Class<R>)` → `Optional<R>` | The job's result, raw or [deserialized](/java/api-reference/result). |
+| `cancel(id)` | Cancel a pending job. |
+| `requestCancel(id)` / `isCancelRequested(id)` | Cooperative cancellation of a running job. |
+| `setProgress(id, int)` | Record 0–100 progress for inspection / the dashboard. |
+
+## Listing & errors
+
+| Method | Description |
+|---|---|
+| `listJobs(JobFilter)` | List jobs — filter by status/queue/task with limit/offset. |
+| `jobErrors(id)` → `List<JobError>` | Per-attempt error history. |
diff --git a/docs/content/docs/java/api-reference/queue/meta.json b/docs/content/docs/java/api-reference/queue/meta.json
new file mode 100644
index 00000000..b7743a29
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Taskito",
+  "pages": ["jobs", "queues", "workers", "resources", "events", "pubsub"]
+}
diff --git a/docs/content/docs/java/api-reference/queue/pubsub.mdx b/docs/content/docs/java/api-reference/queue/pubsub.mdx
new file mode 100644
index 00000000..3e1a542c
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/pubsub.mdx
@@ -0,0 +1,16 @@
+---
+title: Pub/Sub
+description: "Topic subscriptions and fan-out publish. See the Pub/Sub guide for delivery semantics and lifecycle."
+---
+
+See [Pub/Sub](/java/guides/core/pubsub) for the full guide (delivery
+semantics, lifecycle, cross-SDK topics).
+
+| Method | Description |
+|---|---|
+| `subscribe(topic, Task<T>)` / `subscribe(topic, Task<T>, SubscriptionOptions)` | Wire `Task` into `topic`'s routing (durable by default). Register the handler on the worker separately, as for any task. |
+| `publish(topic, payload)` / `publish(topic, payload, PublishOptions)` → `List<Job>` | Fan a message out to every active subscription — one job each. Empty list when nothing is subscribed. |
+| `unsubscribe(topic, name)` | Remove a subscription; `false` if none matched. |
+| `pauseSubscription(topic, name)` / `resumeSubscription(topic, name)` | Stop/resume deliveries without unregistering; `false` if none matched. |
+| `listSubscriptions()` / `listSubscriptions(topic)` | Every subscription, or one topic's active ones. |
+| `listTopics()` | Distinct topics with at least one subscription. |
diff --git a/docs/content/docs/java/api-reference/queue/queues.mdx b/docs/content/docs/java/api-reference/queue/queues.mdx
new file mode 100644
index 00000000..b71c17c9
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/queues.mdx
@@ -0,0 +1,38 @@
+---
+title: Queue & Stats
+description: "Statistics, dead letters, queue control, and settings."
+---
+
+## Statistics
+
+| Method | Description |
+|---|---|
+| `stats()` / `statsByQueue(q)` / `statsAllQueues()` | `QueueStats` counts by status. |
+| `metrics(taskName, sinceMs)` → `List<TaskMetric>` | Per-execution metrics (null task = all). |
+
+## Dead letter
+
+| Method | Description |
+|---|---|
+| `listDead(limit, offset)` / `listDeadByTask(task, limit, offset)` | Dead-letter entries. |
+| `retryDead(deadId)` (alias `retry`) / `deleteDead(deadId)` | Re-enqueue / drop an entry. |
+| `purgeDead(olderThanMs)` / `purgeDeadByTask(task)` | Bulk DLQ cleanup → count removed. |
+
+## Queue control
+
+| Method | Description |
+|---|---|
+| `queue(name)` → `Queue` | A named-queue handle: `name()`, `pause()`, `resume()`, `isPaused()`. |
+| `listPausedQueues()` | Names of every paused queue. |
+
+## Settings
+
+| Method | Description |
+|---|---|
+| `getSetting` / `setSetting` / `deleteSetting` / `listSettings` | Shared key–value settings in the store. |
+
+## Cleanup
+
+| Method | Description |
+|---|---|
+| `purgeCompleted(olderThanMs)` | Drop old completed jobs. |
diff --git a/docs/content/docs/java/api-reference/queue/resources.mdx b/docs/content/docs/java/api-reference/queue/resources.mdx
new file mode 100644
index 00000000..7af212da
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/resources.mdx
@@ -0,0 +1,33 @@
+---
+title: Resources & Locking
+description: "Resources, enqueue gates, and distributed locks."
+---
+
+## Resources
+
+| Method | Description |
+|---|---|
+| `resource(...)` | Register an injectable [resource](/java/api-reference/resources). |
+| `resourceMetrics()` | Per-resource created/disposed/active counters. |
+
+## Enqueue gates
+
+| Method | Description |
+|---|---|
+| `predicate(taskName, Predicate)` / `gate(taskName, EnqueueGate)` | Enqueue-time gates: reject, skip, or defer submissions. |
+| `intercept(Interceptor)` | Pass / convert / redirect / reject each enqueue before serialization. |
+
+## Distributed locks
+
+| Method | Description |
+|---|---|
+| `lock(name, ttlMs)` / `lock(name)` | A distributed `Lock` (default 30s TTL): `acquire()`, `tryAcquire(timeout)`, `extend(ttlMs)`, `close()`. |
+| `withLock(name, ttlMs, Runnable)` | Acquire → run → release; returns whether it ran. |
+| `lockInfo(name)` (alias `getLockInfo`) | Current holder metadata, if held. |
+
+## Periodic
+
+| Method | Description |
+|---|---|
+| `registerPeriodic(PeriodicTask)` | Register (or replace) a cron task → next fire time (Unix ms). |
+| `listPeriodic()` / `deletePeriodic(name)` / `pausePeriodic(name)` / `resumePeriodic(name)` | Periodic task management. |
diff --git a/docs/content/docs/java/api-reference/queue/workers.mdx b/docs/content/docs/java/api-reference/queue/workers.mdx
new file mode 100644
index 00000000..e5828a75
--- /dev/null
+++ b/docs/content/docs/java/api-reference/queue/workers.mdx
@@ -0,0 +1,24 @@
+---
+title: Workers & Hooks
+description: "Worker builder, middleware, and workflow control."
+---
+
+## Workers
+
+| Method | Description |
+|---|---|
+| `worker()` → `Worker.Builder` | Begin building a [worker](/java/api-reference/worker). |
+| `listWorkers()` → `List<WorkerInfo>` | Registered workers (heartbeat + identity). |
+
+## Middleware
+
+| Method | Description |
+|---|---|
+| `use(Middleware)` | Cross-cutting hooks — `onEnqueue`, `before`/`after`/`onError`, and the outcome hooks. |
+
+## Workflows
+
+| Method | Description |
+|---|---|
+| `submitWorkflow(Workflow)` / `submitWorkflow(Workflow, Map)` | Submit a [workflow](/java/api-reference/workflows) → `WorkflowRun`. |
+| `workflowStatus(runId)` / `cancelWorkflow(runId)` | Run queries and cancellation. |
diff --git a/docs/content/docs/node/api-reference/queue.mdx b/docs/content/docs/node/api-reference/queue.mdx
deleted file mode 100644
index ed1c1362..00000000
--- a/docs/content/docs/node/api-reference/queue.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: Queue
-description: "Construct a queue and the full producer/admin API."
----
-
-```ts
-import { Queue } from "@byteveda/taskito";
-
-const queue = new Queue(options);
-```
-
-## Constructor options
-
-| Option | Type | Description |
-|---|---|---|
-| `dbPath` | `string` | SQLite file path (default backend). |
-| `backend` | `"sqlite" \| "postgres" \| "redis"` | Storage backend. |
-| `dsn` | `string` | Connection string for postgres/redis. |
-| `poolSize` | `number` | Connection pool size (sqlite/postgres). |
-| `schema` | `string` | Postgres schema (default `taskito`). |
-| `prefix` | `string` | Redis key prefix. |
-| `namespace` | `string` | Namespace applied to enqueued jobs + the worker scheduler. |
-| `serializer` | `Serializer` | Arg/result serializer (default `JsonSerializer`). |
-| `codec` | `PayloadCodec \| PayloadCodec[]` | Global codec chain wrapping the serializer — covers every payload and result. See [Serializers](/node/api-reference/serializers). |
-| `codecs` | `Record<string, PayloadCodec>` | Named codec registry for per-task `codecs` (payload only). |
-
-## Tasks & enqueue
-
-| Method | Description |
-|---|---|
-| `task(name, fn, config?)` | Register a task. See [Task](/node/api-reference/task). |
-| `configureQueue(name, config)` | Set per-queue rate limit / concurrency. |
-| `enqueue(task, args?, options?)` | Enqueue a job → job id. |
-| `enqueueMany(task, jobs[])` | Batch-enqueue `{ args?, options? }[]` → job ids (no dedup). |
-
-## Results & cancellation
-
-| Method | Description |
-|---|---|
-| `getJob(id)` → `Job \| null` | Fetch a job's current state. |
-| `getResult(id)` | Deserialized result of a completed job, or `undefined` if not yet ready. |
-| `result(id, { timeoutMs?, pollMs? })` | Await a job's terminal result; rejects on failure/cancellation/timeout. |
-| `stream(id, { timeoutMs?, pollMs? })` | Async-iterate a job's [published partials](/node/guides/core/streaming). |
-| `taskLogs(id)` | Raw task-log entries for a job. |
-| `requestCancel(id)` | Request cooperative cancellation of a running job. |
-| `isCancelRequested(id)` | Whether cancellation has been requested for a job. |
-| `cancelJob(id)` | Cancel a pending job. |
-
-## Inspection & management
-
-Scan-heavy calls (marked `Promise` below) run off the JS event loop on a
-background thread pool.
-
-| Method | Description |
-|---|---|
-| `stats()` → `Promise<Stats>` / `statsByQueue(q)` → `Promise<Stats>` / `statsAllQueues()` → `Promise<Record<string, Stats>>` | Counts by status. |
-| `listJobs(filter)` → `Promise<Job[]>` | List jobs. |
-| `getJobErrors(id)` → `Promise<JobError[]>` | Per-attempt error history. |
-| `getMetrics(sinceMs, task?)` → `Promise<Metric[]>` | Raw per-execution metric rows recorded at or after the Unix-ms `sinceMs`. |
-| `deadLetters()` → `Promise<DeadJob[]>` / `retryDead(id)` / `deleteDead(id)` / `purgeDead(ms)` → `Promise<number>` | DLQ (dead-letter queue) ops. |
-| `purgeCompleted(ms)` → `Promise<number>` | Drop old completed jobs. |
-| `pauseQueue(q)` / `resumeQueue(q)` / `listPausedQueues()` | Queue control. |
-| `listWorkers()` → `Promise<WorkerInfo[]>` | Registered workers. |
-
-## Pub/Sub
-
-See [Pub/Sub](/node/guides/core/pubsub) for the full guide (delivery
-semantics, lifecycle, cross-SDK topics).
-
-| Method | Description |
-|---|---|
-| `subscriber(topic, name, fn, options?)` | Register `fn` as `name`, subscribed to `topic`. Returns the queue (chainable, like `task`). |
-| `publish(topic, args?, options?)` → `Promise<Job[]>` | Fan a message out to every active subscription — one job each. Empty array when nothing is subscribed. |
-| `declareSubscriptions()` → `Promise<void>` | Write pending durable subscriptions to storage. Call in a producer-only process; `runWorker()` does this automatically. |
-| `unsubscribe(topic, name)` → `Promise<boolean>` | Remove a subscription. |
-| `pauseSubscription(topic, name)` / `resumeSubscription(topic, name)` → `Promise<boolean>` | Stop/resume deliveries without unregistering. |
-| `listSubscriptions(topic?)` → `Promise<Subscription[]>` | All subscriptions, or one topic's active ones. |
-| `listTopics()` → `Promise<string[]>` | Distinct topics with at least one subscription. |
-| `reapEphemeralSubscriptions()` → `Promise<number>` | Drop ephemeral subscriptions whose owning worker is gone. Runs automatically on the worker heartbeat cadence; exposed for operational tooling. |
-
-## Subsystems
-
-| Member | Description |
-|---|---|
-| `runWorker(options?)` | Start a [worker](/node/api-reference/worker). |
-| `on(event, handler)` | [Events](/node/guides/extensibility/events). |
-| `use(middleware)` | [Middleware](/node/guides/extensibility/middleware) (incl. the `onEnqueue` [interception](/node/guides/resources/interception) hook). |
-| `intercept(interceptor)` | Register an [enqueue interceptor](/node/guides/resources/interception) — runs before defaults, middleware, and gates. |
-| `gate(name, predicate)` | Reject an enqueue when the [predicate](/node/guides/core/predicates) returns `false`. |
-| `resource(name, factory, opts?)` | Register an injectable [resource](/node/guides/resources/dependency-injection) (`scope`, `dispose`). |
-| `webhooks` | [Webhooks](/node/guides/extensibility/webhooks) manager. |
-| `workflows` | [Workflow](/node/api-reference/workflows) builder + queries. |
-| `lock(name, opts)` / `withLock(name, fn)` | [Distributed locks](/node/guides/reliability/locks). |
-| `registerPeriodic(name, task, cron, opts?)` | [Periodic tasks](/node/guides/core/scheduling). |
diff --git a/docs/content/docs/node/api-reference/queue/events.mdx b/docs/content/docs/node/api-reference/queue/events.mdx
new file mode 100644
index 00000000..8928c895
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/events.mdx
@@ -0,0 +1,19 @@
+---
+title: Events & Logs
+description: "Webhook delivery and structured task logs."
+---
+
+## Events & webhooks
+
+Event subscription (`on(event, handler)`) lives on
+[Workers & Hooks](/node/api-reference/queue/workers).
+
+| Member | Description |
+|---|---|
+| `webhooks` | [Webhooks](/node/guides/extensibility/webhooks) manager. |
+
+## Logs
+
+| Method | Description |
+|---|---|
+| `taskLogs(id)` | Raw task-log entries for a job. |
diff --git a/docs/content/docs/node/api-reference/queue/index.mdx b/docs/content/docs/node/api-reference/queue/index.mdx
new file mode 100644
index 00000000..d4df6921
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/index.mdx
@@ -0,0 +1,51 @@
+---
+title: Queue
+description: "Construct a queue and the full producer/admin API."
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+<Callout type="info" title="Sub-pages">
+  The Queue API is split across several pages for readability:
+
+  - **[Job Management](/node/api-reference/queue/jobs)** — fetch jobs, await results, stream partials, cancel
+  - **[Queue & Stats](/node/api-reference/queue/queues)** — statistics, dead letters, pause/resume, cleanup
+  - **[Workers & Hooks](/node/api-reference/queue/workers)** — run workers, list workers, event hooks, middleware
+  - **[Resources & Locking](/node/api-reference/queue/resources)** — resources, enqueue gates, distributed locks, periodic tasks
+  - **[Events & Logs](/node/api-reference/queue/events)** — webhooks, task logs
+  - **[Pub/Sub](/node/api-reference/queue/pubsub)** — topic subscriptions, fan-out publish
+</Callout>
+
+```ts
+import { Queue } from "@byteveda/taskito";
+
+const queue = new Queue(options);
+```
+
+## Constructor options
+
+| Option | Type | Description |
+|---|---|---|
+| `dbPath` | `string` | SQLite file path (default backend). |
+| `backend` | `"sqlite" \| "postgres" \| "redis"` | Storage backend. |
+| `dsn` | `string` | Connection string for postgres/redis. |
+| `poolSize` | `number` | Connection pool size (sqlite/postgres). |
+| `schema` | `string` | Postgres schema (default `taskito`). |
+| `prefix` | `string` | Redis key prefix. |
+| `namespace` | `string` | Namespace applied to enqueued jobs + the worker scheduler. |
+| `serializer` | `Serializer` | Arg/result serializer (default `JsonSerializer`). |
+| `codec` | `PayloadCodec \| PayloadCodec[]` | Global codec chain wrapping the serializer — covers every payload and result. See [Serializers](/node/api-reference/serializers). |
+| `codecs` | `Record<string, PayloadCodec>` | Named codec registry for per-task `codecs` (payload only). |
+
+## Tasks & enqueue
+
+| Method | Description |
+|---|---|
+| `task(name, fn, config?)` | Register a task. See [Task](/node/api-reference/task). |
+| `configureQueue(name, config)` | Set per-queue rate limit / concurrency. |
+| `enqueue(task, args?, options?)` | Enqueue a job → job id. |
+| `enqueueMany(task, jobs[])` | Batch-enqueue `{ args?, options? }[]` → job ids (no dedup). |
+
+## Related
+
+- [`workflows`](/node/api-reference/workflows) — Workflow builder + queries, exposed as `queue.workflows`.
diff --git a/docs/content/docs/node/api-reference/queue/jobs.mdx b/docs/content/docs/node/api-reference/queue/jobs.mdx
new file mode 100644
index 00000000..bbec5d11
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/jobs.mdx
@@ -0,0 +1,26 @@
+---
+title: Job Management
+description: "Fetching jobs, awaiting results, streaming partials, cancellation, listing, and errors."
+---
+
+## Results & cancellation
+
+| Method | Description |
+|---|---|
+| `getJob(id)` → `Job \| null` | Fetch a job's current state. |
+| `getResult(id)` | Deserialized result of a completed job, or `undefined` if not yet ready. |
+| `result(id, { timeoutMs?, pollMs? })` | Await a job's terminal result; rejects on failure/cancellation/timeout. |
+| `stream(id, { timeoutMs?, pollMs? })` | Async-iterate a job's [published partials](/node/guides/core/streaming). |
+| `requestCancel(id)` | Request cooperative cancellation of a running job. |
+| `isCancelRequested(id)` | Whether cancellation has been requested for a job. |
+| `cancelJob(id)` | Cancel a pending job. |
+
+## Job listing & errors
+
+Scan-heavy calls (marked `Promise` below) run off the JS event loop on a
+background thread pool.
+
+| Method | Description |
+|---|---|
+| `listJobs(filter)` → `Promise<Job[]>` | List jobs. |
+| `getJobErrors(id)` → `Promise<JobError[]>` | Per-attempt error history. |
diff --git a/docs/content/docs/node/api-reference/queue/meta.json b/docs/content/docs/node/api-reference/queue/meta.json
new file mode 100644
index 00000000..5b6f5556
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/meta.json
@@ -0,0 +1 @@
+{ "title": "Queue", "pages": ["jobs", "queues", "workers", "resources", "events", "pubsub"] }
diff --git a/docs/content/docs/node/api-reference/queue/pubsub.mdx b/docs/content/docs/node/api-reference/queue/pubsub.mdx
new file mode 100644
index 00000000..4d15ab66
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/pubsub.mdx
@@ -0,0 +1,18 @@
+---
+title: Pub/Sub
+description: "Topic subscriptions and fan-out publish."
+---
+
+See [Pub/Sub](/node/guides/core/pubsub) for the full guide (delivery
+semantics, lifecycle, cross-SDK topics).
+
+| Method | Description |
+|---|---|
+| `subscriber(topic, name, fn, options?)` | Register `fn` as `name`, subscribed to `topic`. Returns the queue (chainable, like `task`). |
+| `publish(topic, args?, options?)` → `Promise<Job[]>` | Fan a message out to every active subscription — one job each. Empty array when nothing is subscribed. |
+| `declareSubscriptions()` → `Promise<void>` | Write pending durable subscriptions to storage. Call in a producer-only process; `runWorker()` does this automatically. |
+| `unsubscribe(topic, name)` → `Promise<boolean>` | Remove a subscription. |
+| `pauseSubscription(topic, name)` / `resumeSubscription(topic, name)` → `Promise<boolean>` | Stop/resume deliveries without unregistering. |
+| `listSubscriptions(topic?)` → `Promise<Subscription[]>` | All subscriptions, or one topic's active ones. |
+| `listTopics()` → `Promise<string[]>` | Distinct topics with at least one subscription. |
+| `reapEphemeralSubscriptions()` → `Promise<number>` | Drop ephemeral subscriptions whose owning worker is gone. Runs automatically on the worker heartbeat cadence; exposed for operational tooling. |
diff --git a/docs/content/docs/node/api-reference/queue/queues.mdx b/docs/content/docs/node/api-reference/queue/queues.mdx
new file mode 100644
index 00000000..8320fb0b
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/queues.mdx
@@ -0,0 +1,32 @@
+---
+title: Queue & Stats
+description: "Queue statistics, dead letter operations, pause/resume, and cleanup."
+---
+
+Scan-heavy calls (marked `Promise` below) run off the JS event loop on a
+background thread pool.
+
+## Statistics
+
+| Method | Description |
+|---|---|
+| `stats()` → `Promise<Stats>` / `statsByQueue(q)` → `Promise<Stats>` / `statsAllQueues()` → `Promise<Record<string, Stats>>` | Counts by status. |
+| `getMetrics(sinceMs, task?)` → `Promise<Metric[]>` | Raw per-execution metric rows recorded at or after the Unix-ms `sinceMs`. |
+
+## Dead letter
+
+| Method | Description |
+|---|---|
+| `deadLetters()` → `Promise<DeadJob[]>` / `retryDead(id)` / `deleteDead(id)` / `purgeDead(ms)` → `Promise<number>` | DLQ (dead-letter queue) ops. |
+
+## Queue control
+
+| Method | Description |
+|---|---|
+| `pauseQueue(q)` / `resumeQueue(q)` / `listPausedQueues()` | Queue control. |
+
+## Cleanup
+
+| Method | Description |
+|---|---|
+| `purgeCompleted(ms)` → `Promise<number>` | Drop old completed jobs. |
diff --git a/docs/content/docs/node/api-reference/queue/resources.mdx b/docs/content/docs/node/api-reference/queue/resources.mdx
new file mode 100644
index 00000000..2958bd41
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/resources.mdx
@@ -0,0 +1,29 @@
+---
+title: Resources & Locking
+description: "Injectable resources, enqueue gates, distributed locks, and periodic tasks."
+---
+
+## Resources
+
+| Member | Description |
+|---|---|
+| `resource(name, factory, opts?)` | Register an injectable [resource](/node/guides/resources/dependency-injection) (`scope`, `dispose`). |
+
+## Enqueue gates
+
+| Member | Description |
+|---|---|
+| `intercept(interceptor)` | Register an [enqueue interceptor](/node/guides/resources/interception) — runs before defaults, middleware, and gates. |
+| `gate(name, predicate)` | Reject an enqueue when the [predicate](/node/guides/core/predicates) returns `false`. |
+
+## Distributed locks
+
+| Member | Description |
+|---|---|
+| `lock(name, opts)` / `withLock(name, fn)` | [Distributed locks](/node/guides/reliability/locks). |
+
+## Periodic
+
+| Member | Description |
+|---|---|
+| `registerPeriodic(name, task, cron, opts?)` | [Periodic tasks](/node/guides/core/scheduling). |
diff --git a/docs/content/docs/node/api-reference/queue/workers.mdx b/docs/content/docs/node/api-reference/queue/workers.mdx
new file mode 100644
index 00000000..c4d4bcdf
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue/workers.mdx
@@ -0,0 +1,18 @@
+---
+title: Workers & Hooks
+description: "Run workers, list registered workers, event hooks, and middleware."
+---
+
+## Workers
+
+| Method | Description |
+|---|---|
+| `runWorker(options?)` | Start a [worker](/node/api-reference/worker). |
+| `listWorkers()` → `Promise<WorkerInfo[]>` | Registered workers. |
+
+## Hooks & middleware
+
+| Member | Description |
+|---|---|
+| `on(event, handler)` | [Events](/node/guides/extensibility/events). |
+| `use(middleware)` | [Middleware](/node/guides/extensibility/middleware) (incl. the `onEnqueue` [interception](/node/guides/resources/interception) hook). |