Site docs generator

.github/crates.txt

@@ -0,0 +1 @@
+taskvisor

.github/workflows/manual.yml

@@ -15,3 +15,7 @@ jobs:
   ci:
     name: ci
     uses: soltiHQ/actions/.github/workflows/rust-ci.yml@v1
+
+  docs:
+    name: docs
+    uses: soltiHQ/actions/.github/workflows/docs-ci.yml@v1

.github/workflows/pr-action.yml

@@ -17,3 +17,7 @@ jobs:
   ci:
     name: ci
     uses: soltiHQ/actions/.github/workflows/rust-ci.yml@v1
+
+  docs:
+    name: docs
+    uses: soltiHQ/actions/.github/workflows/docs-ci.yml@v1

.github/workflows/tag-publish.yml

@@ -19,6 +19,20 @@ jobs:
     name: release
     uses: soltiHQ/actions/.github/workflows/rust-release.yml@v1
     with:
-      crate: taskvisor
+      crates-file: .github/crates.txt
     secrets:
       crates-io-token: ${{ secrets.CRATES_IO_TOKEN }}
+
+  docs:
+    name: docs
+    needs: release
+    uses: soltiHQ/actions/.github/workflows/docs-notify.yml@v1
+    with:
+      site-repository: soltiHQ/site
+      site-workflow: docs-release.yml
+      site-ref: main
+      source-repository: ${{ github.repository }}
+      source-ref: ${{ github.ref_name }}
+      client-id: ${{ vars.DOCS_SITE_APP_CLIENT_ID }}
+    secrets:
+      private-key: ${{ secrets.DOCS_SITE_APP_PRIVATE_KEY }}

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name         = "taskvisor"
-version      = "0.8.0"
+version      = "0.8.1"
 edition      = "2024"
 rust-version = "1.90.0"
 

README.md

@@ -13,7 +13,7 @@ It turns ordinary async work into a managed lifecycle with backoff, timeouts, ca
 When work competes for the same application key, the optional controller queues it, replaces older work, or rejects it.
 Conflict policy is evaluated per key; supervisor-wide limits still apply.
 
-[Quick start](#quick-start) · [User guide](guide.md) · [API docs](https://docs.rs/taskvisor) · [Examples](examples/README.md) · [Benchmarks](benches/README.md)
+[Quick start](#quick-start) · [User guide](docs/index.md) · [API docs](https://docs.rs/taskvisor) · [Examples](examples/README.md) · [Benchmarks](benches/README.md)
 
 ## The retry loop you stop maintaining
 
@@ -146,7 +146,7 @@ The `controller` feature is enabled by default.
 A supervisor uses controller admission only when it is built with `SupervisorBuilder::with_controller`.
 
 See [tenant_sync.rs](examples/tenant_sync.rs) for a complete latest-wins workflow across separate tenant slots.
-The [user guide](guide.md#coordinate-work-by-key) explains queue ordering, replacement, rejection, slot identity, and controller limits.
+The [user guide](docs/keyed-admission.md) explains queue ordering, replacement, rejection, slot identity, and controller limits.
 
 ## When Taskvisor fits
 
@@ -183,7 +183,7 @@ Taskvisor makes its process boundary explicit:
 - periodic tasks use a delay after completion, not a calendar or cron schedule;
 - controller slots coordinate work inside one supervisor.
 
-Read the [full production boundaries](guide.md#production-boundaries) before deploying a service.
+Read the [full production boundaries](docs/production-boundaries.md) before deploying a service.
 
 ## Examples and documentation
 
@@ -199,8 +199,8 @@ The repository contains 18 complete runnable programs.
 
 The [examples guide](examples/README.md) provides the complete learning path, run commands, feature flags, and stop behavior.
 
-Use the [user guide](guide.md) for application workflows and production boundaries, then open the [API documentation](https://docs.rs/taskvisor) for exact contracts.
-Optional `tracing`, `logging`, `tokio-util-interop`, and `test-util` integrations are covered in the [installation guide](guide.md#install-taskvisor).
+Use the [user guide](docs/index.md) for application workflows and production boundaries, then open the [API documentation](https://docs.rs/taskvisor) for exact contracts.
+The [installation guide](docs/installation.md) lists the optional `tracing`, `logging`, `tokio-util-interop`, and `test-util` features. Use the [API documentation](https://docs.rs/taskvisor) for each integration's exact public contract.
 
 ## Benchmarks
 

Taskfile.yml

@@ -1,9 +1,15 @@
 version: '3'
 
 includes:
+  docs:
+    taskfile: https://raw.githubusercontent.com/soltiHQ/actions/v1/taskfiles/docs/Taskfile.yml
   rust:
     taskfile: https://raw.githubusercontent.com/soltiHQ/actions/v1/taskfiles/rust/Taskfile.yml
 
+vars:
+  docs_version:
+    sh: sed -n 's/^version[[:space:]]*=[[:space:]]*"\([^"]*\)"/\1/p' Cargo.toml | head -n 1
+
 tasks:
   ci/fmt:
     desc: Run 'cargo fmt --check'.
@@ -38,12 +44,10 @@ tasks:
         vars: { TEST_ARGS: '--all-features --locked' }
 
   ci/test-unit:
-    desc: Run unit tests ('cargo test --lib') and doctests ('cargo test --doc').
+    desc: Run unit tests ('cargo test --lib').
     cmds:
       - task: rust:test
         vars: { TEST_ARGS: '--lib --all-features --locked' }
-      - task: rust:test
-        vars: { TEST_ARGS: '--doc --all-features --locked' }
 
   ci/test-integration:
     desc: Run integration tests ('cargo test --test "*"').
@@ -57,14 +61,31 @@ tasks:
       - task: rust:audit
 
   ci/docs:
-    desc: Run 'rustdoc' for the taskvisor crate. Fails on broken doc links in any feature config.
+    desc: Validate API documentation and the versioned user guide.
     cmds:
       - task: rust:doc
         vars: { DOC_ARGS: '--locked --no-deps' }
       - task: rust:doc
         vars: { DOC_ARGS: '--locked --no-deps --all-features' }
       - task: rust:docs
         vars: { DOCS_ARGS: '--all-features --locked' }
+      - task: docs:validate
+        vars:
+          VERSION: '{{.docs_version}}'
+          PRODUCT: taskvisor
+          TITLE: Taskvisor
+          REPOSITORY: https://github.com/soltiHQ/taskvisor
+          VERSION_PROVIDER: cargo
+          VERSION_PACKAGE: taskvisor
+          REFERENCE_LABEL: API reference
+          REFERENCE_URL: https://docs.rs/taskvisor/{version}/taskvisor/
+          CARGO_SNIPPET_SOURCES: README.md docs/installation.md
+          LINK_SOURCES: docs README.md guide.md src/lib.rs
+      - task: docs:links/external
+        vars:
+          LINK_SOURCES: docs README.md guide.md src/lib.rs
+      - task: rust:test
+        vars: { TEST_ARGS: '--doc --all-features --locked' }
 
   ci/build:
     desc: Build all examples for a package. Pass CRATE.

docs/cancellation-and-shutdown.md

@@ -0,0 +1,60 @@
+---
+title: Cancellation and shutdown
+description: Make task operations cancellation-aware and join Taskvisor's bounded shutdown workflow.
+---
+
+# Cancellation and shutdown
+
+Cancellation starts cooperatively. A resident task must observe `TaskContext`:
+
+```rust
+use taskvisor::{TaskContext, TaskError};
+
+async fn do_work() -> Result<(), TaskError> {
+    // Application work goes here.
+    Ok(())
+}
+
+async fn run_one_operation(ctx: &TaskContext) -> Result<(), TaskError> {
+    ctx.run_until_cancelled(do_work()).await?
+}
+
+async fn run_with_more_branches(ctx: &TaskContext) -> Result<(), TaskError> {
+    tokio::select! {
+        _ = ctx.cancelled() => Err(TaskError::Canceled),
+        result = do_work() => result,
+    }
+}
+```
+
+`run_until_cancelled` drops the wrapped future when cancellation wins.
+Cancellation wins a tie, and an already-cancelled context does not poll the wrapped future.
+Use it only when dropping that future is a safe way to cancel the exact operation.
+Check the operation's cancellation-safety contract; an external commit, acknowledgement, or partially consumed input may need an explicit protocol.
+The Tokio sleep in [graceful_worker.rs](../examples/graceful_worker.rs) is a simple drop-safe example.
+
+An attempt timeout also drops the attempt future.
+It does not undo side effects that already happened.
+A blocking future destructor can delay attempt release beyond the configured timeout.
+
+`cancel_with_timeout` and `cancel_by_name_with_timeout` limit how long the caller waits for registered task cleanup.
+Controller ordering, command-queue admission, and the registry claim happen outside that timer.
+A timeout stops this caller's wait; it does not undo cancellation or change the supervisor grace period.
+If task completion is observed at the timeout boundary, completion wins.
+Queued controller work is removed directly, and `cancel_with_timeout` does not apply its wait timer to that path.
+A watched queued submission then resolves to `Rejected` with `RejectionKind::RemovedFromQueue`, not to `Canceled`.
+The matching `try_*` methods make command-queue admission fail fast; their remaining behavior is unchanged.
+
+The joined shutdown workflow has concurrent parts:
+
+- It closes admission and signals runtime and controller shutdown.
+- The registry requests cancellation for registered tasks, waits through the configured grace period, and commits `ForceAborted` for tasks that did not stop in time.
+- The controller rejects pending submissions as its loop exits; this can overlap the registry grace period.
+- Taskvisor joins the remaining runtime and controller cleanup, then drains subscriber queues up to their separate deadline.
+
+Taskvisor cannot interrupt synchronous code in the middle of a poll.
+After the grace period, the final outcome may be `ForceAborted` while that synchronous code is still physically running.
+The supervisor keeps ownership until it returns.
+
+`handle.shutdown().await` joins the shared shutdown workflow and returns its result.
+Dropping the final public owner can request cancellation, but a destructor cannot await cleanup or report its errors.

docs/common-mistakes.md

@@ -0,0 +1,24 @@
+---
+title: Common mistakes
+description: Avoid incorrect assumptions about task results, admission, cancellation, blocking work, and side effects.
+---
+
+# Common mistakes
+
+- Treating `run().await == Ok(())` as proof that every task succeeded.
+- Treating `submit().await?` as positive slot admission.
+- Using best-effort events for application decisions.
+- Forgetting to observe cancellation in a resident task.
+- Treating a controller slot as a registered task name.
+- Running blocking or CPU-heavy work on Tokio worker threads.
+- Assuming a timeout or force-abort can undo external side effects.
+
+## Continue learning
+
+| Resource                                          | Next step                                          |
+|---------------------------------------------------|----------------------------------------------------|
+| [Examples guide](../examples/README.md)           | Choose a complete runnable scenario.               |
+| [API documentation](https://docs.rs/taskvisor)    | Read exact contracts for public types and methods. |
+| [Benchmark guide](../benches/README.md)           | Run and interpret the Criterion suites.            |
+| [Contributor map](../src/ARCHITECTURE.md)         | Follow runtime ownership and source boundaries.    |
+

docs/configuration.md

@@ -0,0 +1,72 @@
+---
+title: Configure Taskvisor
+description: Configure runtime limits, inherited task behavior, per-task overrides, subscriber queues, and keyed admission limits.
+---
+
+# Configure Taskvisor
+
+Configuration is split by concern:
+
+```text
+SupervisorConfig ──► runtime-wide limits and shutdown
+TaskDefaults ──────► inherited task behavior
+TaskSpec ──────────► per-task overrides
+ControllerConfig ──► keyed-admission limits
+Subscribe ─────────► per-subscriber event queue capacity
+```
+
+```rust
+use std::num::{NonZeroU32, NonZeroUsize};
+use std::sync::Arc;
+use std::time::Duration;
+use taskvisor::{Supervisor, SupervisorConfig, TaskDefaults};
+
+fn configured_supervisor() -> Arc<Supervisor> {
+    let runtime = SupervisorConfig::default()
+        .with_grace(Duration::from_secs(30))
+        .with_subscriber_shutdown_timeout(Duration::from_secs(5))
+        .with_max_concurrent(NonZeroUsize::new(16))
+        .with_ownership_capacity(NonZeroUsize::new(4096));
+
+    let tasks = TaskDefaults::default()
+        .with_timeout(Duration::from_secs(20))
+        .with_max_retries(NonZeroU32::new(5).unwrap());
+
+    Supervisor::builder(runtime)
+        .with_task_defaults(tasks)
+        .build()
+}
+```
+
+Main defaults:
+
+| Setting                   | Default                                                                                |
+|---------------------------|----------------------------------------------------------------------------------------|
+| Graceful task shutdown    | 60 seconds.                                                                            |
+| Subscriber drain          | 5 seconds, shared by all subscriber queues.                                            |
+| Concurrent task attempts  | Unlimited.                                                                             |
+| Registered-task limit     | 1024.                                                                                  |
+| Ownership capacity        | 1024 per supervisor across accepted tasks and subscribers.                             |
+| Event bus capacity        | 1024.                                                                                  |
+| Subscriber queue capacity | 1024 per subscriber; override through `queue_capacity`.                                |
+| Registry command capacity | 1024.                                                                                  |
+| Restart policy            | On retryable failure.                                                                  |
+| Failure backoff           | 200 ms initial base, capped at 30 s, with equal jitter; the first delay is 100–200 ms. |
+| Attempt timeout           | None.                                                                                  |
+| Failure retry limit       | Unlimited.                                                                             |
+
+Three limits answer different questions:
+
+| Limit                  | What it bounds                                                                                        |
+|------------------------|-------------------------------------------------------------------------------------------------------|
+| `max_concurrent`       | Attempts physically running at the same time.                                                         |
+| `max_registered_tasks` | Registered and removing tasks through terminal cleanup; force-aborted work can remain charged longer. |
+| `ownership_capacity`   | Accepted task and subscriber values still owned through physical cleanup.                             |
+
+`SupervisorConfig::with_ownership_capacity(None)` removes the ownership count bound.
+Cleanup still uses a bounded worker set, but retained values and cleanup backlog can then grow without a count limit.
+
+During cleanup handoff, one task can temporarily consume two `max_registered_tasks` units.
+
+Capacity values are non-zero where zero would make the runtime unusable.
+Checked `try_with_*` methods accept raw integers and return a configuration error for invalid values.

docs/defining-tasks.md

@@ -0,0 +1,40 @@
+---
+title: Define a task
+description: Define Taskvisor work with an async closure or a reusable task type.
+---
+
+# Define a task
+
+Use `TaskFn` for an async closure:
+
+```rust
+use taskvisor::{TaskFn, TaskRef};
+
+let task: TaskRef = TaskFn::arc(|_ctx| async {
+    println!("one attempt");
+    Ok(())
+});
+```
+
+Implement `Task` when a reusable type should hold state or dependencies across attempts.
+Each call to `Task::spawn` must return a fresh future.
+Keep synchronous work in `spawn` short; put the actual operation inside the returned future.
+
+A shared `TaskRef` can back several registrations. Registrations that overlap in one supervisor need different names.
+A name can be reused after the earlier registration releases it.
+The registrations receive different task IDs, and their `spawn` calls may run concurrently when configured attempt capacity permits.
+Shared task state must support that use.
+
+After a force-abort, Taskvisor may keep the name reserved until it observes that the task attempt has physically returned.
+
+Keep blocking and CPU-heavy work away from Tokio worker threads.
+Use a suitable blocking executor, worker pool, or external runtime.
+Also keep the destructor of an attempt future short: Taskvisor drops that future synchronously when the attempt ends or is canceled.
+
+Runnable examples:
+
+- [basic.rs](../examples/basic.rs) uses `TaskFn` for one static task;
+- [task_type.rs](../examples/task_type.rs) implements `Task` for reusable state;
+- [queue_consumer.rs](../examples/queue_consumer.rs) supervises a cancellation-aware receive loop;
+- [cpu_job.rs](../examples/cpu_job.rs) moves CPU work to Rayon and explains the cancellation limit.
+

docs/index.md

@@ -0,0 +1,24 @@
+---
+title: Taskvisor user guide
+description: Choose the Taskvisor workflow that fits an application and follow its production boundaries.
+---
+
+# Taskvisor user guide
+
+This guide explains how to use Taskvisor in an application and how to choose between its public workflows.
+For exact method signatures, error variants, and edge-case contracts, use the [API documentation](https://docs.rs/taskvisor).
+
+Taskvisor is an in-process runtime. Tasks, queued submissions, task IDs, events, and watched outcomes do not survive process exit.
+Use durable external storage when work must resume after a restart.
+
+- New to Taskvisor? Run the [Quick start](../README.md#quick-start).
+- Looking for a complete program? Follow the [examples guide](../examples/README.md).
+- Changing Taskvisor itself? Start with the [contributor map](../src/ARCHITECTURE.md).
+
+## In this guide
+
+- Start: [mental model](mental-model.md), [installation](installation.md), [task definition](defining-tasks.md), and [task behavior](lifecycle-policies.md).
+- Run: [supervisor entry points and runtime management](running-and-managing.md), then [cancellation and shutdown](cancellation-and-shutdown.md).
+- Extend: [outcomes and events](outcomes-and-events.md), [per-key coordination](keyed-admission.md), and [configuration](configuration.md).
+- Deploy: [production boundaries](production-boundaries.md) and [common mistakes](common-mistakes.md).
+