# Docs - [Agora](/docs): The AdonisJS ecosystem — context, diagnostics, resilience, durable, telescope, authz, collaboration, media, filter, payments, agent and authkit. - [Conventions](/docs/conventions): Cross-cutting conventions every @adonis-agora/* library follows — pagination shapes, the meta envelope, and what `limit` is reserved for. - **Libraries** - Context: Ambient request/tenant/correlation context that crosses HTTP, queue, durable and ace boundaries. - [Context](/docs/context): A module-level AsyncLocalStorage for AdonisJS that carries user, tenant and traceId across every boundary — HTTP, queue, durable and ace. - [Getting Started](/docs/context/getting-started): Configure @adonis-agora/context, read the traceId anywhere, and populate the user and tenant from your auth layer. - [The Store](/docs/context/the-store): The ContextStore shape, why it carries a UserRef instead of the full user, the always-present traceId invariant, and how to add your own typed fields. - [Cross-Process](/docs/context/cross-process): Carry the context across queue, durable and ace boundaries with serialize() / deserialize(), bind(), and W3C baggage — the hard part that justifies the library. - [Database per Tenant](/docs/context/database-per-tenant): Resolve the right Lucid connection from the tenant in context — fail-closed, so a request without a tenant never silently reads the default database. - [Customization](/docs/context/customization): The five levels of customizing @adonis-agora/context — custom fields, populating values, non-HTTP entrypoints, the cross-process carrier, and swapping the accessor. - [Testing](/docs/context/testing): Run unit tests inside a fake context store with runWithContext and enterContext from @adonis-agora/context/testing. - Diagnostics: A zero-dependency diagnostics bus over node:diagnostics_channel, with an OpenTelemetry auto-bridge. - [Diagnostics](/docs/diagnostics): A zero-dependency diagnostics bus over node:diagnostics_channel — emit once, observe anywhere, with an OpenTelemetry auto-bridge. - [Getting Started](/docs/diagnostics/getting-started): Install and configure the package, emit POINT events, trace spans, and correlate everything with a trace id. - [Typed payloads](/docs/diagnostics/typed-payloads): Opt into compile-time payload types for emit() and trace() by augmenting the ChannelRegistry via declaration merging — plus the CapabilityRegistry, the same mechanism applied to the globalThis capability slots. - [Consumers](/docs/diagnostics/consumers): Observe diagnostic events from anywhere — onDiagnostic, the channel registry, your own subscriber, OpenTelemetry, an APM, and tests. - [Transports](/docs/diagnostics/transports): Fan diagnostics events out across processes — pick a transport (Redis or @adonisjs/queue) in config/diagnostics.ts, exactly like a session or cache store. - **Integrations** - [OpenTelemetry](/docs/diagnostics/opentelemetry): A zero-config bridge that turns trace() spans into real OTel spans, records emits as span events, and publishes the W3C traceparent. - [Claim registry](/docs/diagnostics/claims): How a lib-specific watcher claims a diagnostics channel so the generic OTel bridge dedups — recording each event once, not twice. - Resilience: Composable timeout, retry, circuit-breaker and failover policies with a pluggable breaker store. - [Resilience](/docs/resilience): Composable resilience policies for AdonisJS — timeout, retry, circuit breaker and failover, with a pluggable, distributed circuit-breaker store. - [Getting Started](/docs/resilience/getting-started): Install @adonis-agora/resilience, wrap a flaky call with a composed policy, then register named policies in config and reach them through the container. - [Policies](/docs/resilience/policies): The policy engine — timeout, retry with backoff, circuit breaker, wrap composition, and the list-oriented failover primitive, plus the typed errors they throw. - [Declarative usage](/docs/resilience/decorator): Wrap a class method with timeout, retry and circuit-breaker policies declaratively using the @withResilience decorator — the ergonomic counterpart to wrap(...). - [Service & Config](/docs/resilience/adonis): Register named policies in config/resilience.ts, let the provider bind a singleton ResilienceService, and run policies + inspect circuits through the container. - [Stores](/docs/resilience/stores): Share circuit-breaker state across instances with a config-driven ResilienceStore — in-memory by default, or Lucid (SQL) / Redis drivers selected in config/resilience.ts that coordinate the half-open probe atomically. - [Building a custom store](/docs/resilience/custom-store): Back the circuit breaker with any engine — reuse the SQL base and a tiny SqlDriver, reuse the pure state machine (computeAdmit / computeRecord), or implement ResilienceStore from scratch — then wire it through the ResilienceService. - [Integrations](/docs/resilience/integrations): Emit state transitions over @adonis-agora/diagnostics (for Telescope), mirror them onto an EventEmitter, and make breaker keys tenant-aware through @adonis-agora/context — all soft-detected and optional. - [Testing](/docs/resilience/testing): Drive time deterministically with FakeClock so timeouts, backoff and cooldowns are instant and reproducible — and validate a custom store against the shared contract suite. - Durable: Durable, resumable, cross-process workflows for AdonisJS — built on @adonisjs/queue. - [Durable](/docs/durable): Durable workflows for AdonisJS — write a workflow as plain code; every step is checkpointed, so it survives crashes and deploys. Steps can run across processes, with a built-in control plane. - [Getting Started](/docs/durable/getting-started): Run your first durable workflow in an AdonisJS app — install, configure, register a workflow, and start a run. Zero infrastructure with the in-process transport and in-memory store. - **Guides** - Concepts - [Durability & replay](/docs/durable/concepts/durability): How checkpoint-and-replay makes a workflow survive crashes — and the one rule it imposes. The workflow body must be deterministic; all side effects live in steps. - [Workflows & steps](/docs/durable/concepts/workflows-and-steps): Registering workflows with engine.register, dispatched steps with ctx.step (string name, @Step, or defineStep), the in-process ctx.localStep escape hatch, ctx.sideEffect/ctx.now for determinism, retries, fan-out, fatal errors, sub-process events, and tags. - [Sleep & signals](/docs/durable/concepts/sleep-and-signals): Pause a workflow durably — ctx.sleep for time-based waits (minutes to months, no compute), ctx.waitForSignal for human approvals and webhooks, and ctx.waitForEvent for name-based pub/sub with reliable (buffered) delivery, all surviving restarts. - [Tenancy](/docs/durable/concepts/tenancy): The two isolation axes — namespace on the engine and partition on the transport — what each one actually partitions, and the boundary that keeps a store-less pod to its own runs. - Authoring - [app/workflows & make:workflow](/docs/durable/authoring/app-workflows): The class-based authoring convention — a BaseWorkflow subclass per file under app/workflows with a static workflow config, auto-registered at boot, scaffolded by make:workflow. The parallel to @adonisjs/queue's app/jobs and make:job. - [Child workflows](/docs/durable/authoring/child-workflows): Compose workflows by calling other workflows — await a child's result with Inner.start (or ctx.child), kick one off fire-and-forget with Inner.dispatch (or ctx.startChild), or fan out over a list with ctx.all. The same statics work at the top level, context-aware. - [Durable entities](/docs/durable/authoring/entities): Keyed virtual actors — engine.registerEntity defines a named entity whose handlers run serialized per key over durable state (exactly once). Drive it with engine.signalEntity / ctx.callEntity, read it with engine.getEntityState. The durable answer to a per-user counter or per-account balance without DB locks. - [Queries & updates](/docs/durable/authoring/queries-and-updates): Read a live run's state with ctx.setEvent + engine.getEvent (side-effect-free queries), steer it with ctx.onUpdate + engine.registerUpdateValidator + engine.update (validated, Temporal-style updates that can be rejected before they touch the run), and index runs with search attributes for typed/range engine.listRuns filtering. - [Durable webhooks](/docs/durable/authoring/webhooks): ctx.webhook() mints a durable callback handle with a deterministic token and a public url; hand the url to a third party inside a step, then await handle.wait() to suspend with zero compute until the callback arrives as engine.signal(token, body). - [External tasks & control primitives](/docs/durable/authoring/external-tasks): ctx.task pairs with engine.completeTask/failTask to call a foreign system, suspend with zero compute, and resume on its callback (async completion). Plus ctx.transaction for a step that checkpoints in the same DB transaction as its write, and ctx.breakpoint to pause a run for a human from the dashboard. - [Versioning & determinism](/docs/durable/authoring/versioning): Keeping in-flight runs replay-safe across code changes — workflow versions for breaking changes, the NonDeterminismError guard, the deterministic ctx.now and ctx.sideEffect capture sources, and ctx.patched for guarding an in-place change without a new version. - [Scheduling](/docs/durable/authoring/scheduling): Recurring workflows with ScheduledWorkflow — fixed intervals via everyMs or DST-aware cron via cron + timezone — registered under schedules in config/durable.ts and fired by the durable:work worker tick, started exactly once per window by an idempotent time-bucket run id, with runtime pause/resume/trigger control via engine.listSchedules, setSchedulePaused and triggerSchedule. - [Event-triggered workflows](/docs/durable/authoring/event-triggers): Start a workflow when an external event fires — an AdonisJS emitter event (`@OnEvent`) or a `@adonis-agora/diagnostics` channel (`@OnDiagnostic`) — with the event payload as the run input. - Reliability - [Reliability](/docs/durable/reliability): How @adonis-agora/durable keeps long-running work correct in the face of transient failures, crashes and overload — step retries, saga compensation, durable flow-control queues and the dead-letter queue. - [Retries & backoff](/docs/durable/reliability/retries): In-process localStep retries with fixed/exponential backoff and jitter, FatalError to opt out, the durable dispatched-step retry path (re-dispatch on a persisted wakeAt), retryable:false worker verdicts, and the in-memory timeoutMs + heartbeat liveness path. - [Sagas & compensation](/docs/durable/reliability/sagas): Undo the side effects of a partially-completed run with per-step compensate callbacks that run in reverse on failure, compensationRetries and compensationTimeoutMs for transient/lost undos, checkpointed (crash-safe) unwinds, compensate: events, and compensating cancellation via engine.cancel(runId, { compensate: true }). - [Flow control](/docs/durable/reliability/flow-control): Durable queues for dispatched steps — cap concurrency and enforce fixed- or sliding-window rate limits with engine.registerQueue and ctx.step(step, input, { queue }). A blocked call re-suspends and the timer poller retries admission. Scale the cap across processes with @adonis-agora/durable/admission-redis. - [Dead-letter queue](/docs/durable/reliability/dead-letter): Cap crash-recovery with maxRecoveryAttempts so a poison-pill run moves to the terminal dead status instead of crash-looping forever, then route dead runs with engine.onDead to alert, compensate, or start a durable handler workflow. - [Retention & archival](/docs/durable/reliability/retention): Hard-delete terminal runs past a per-status age with the retention config, swept by the durable:work tick (throttled to one pass a minute), and archive each run before deletion with engine.onEvict — a throwing hook skips the delete, so a broken archive never loses data. - [Failure modes & recovery](/docs/durable/reliability/failure-modes): An operator-facing map from symptom to knob — where a run actually executes (runDispatcher), what reclaims a worker that crashed mid-run, why a lost remote dispatch does NOT auto-redrive by design, the three nets that catch it (timeoutMs, remoteRedispatchMs, redispatchPending), the stalled-run pager (engine.onStalled + stalledAfter), queue-transport specifics, namespaces, and how to reproduce each failure in a test. - [Delivery under multiple instances](/docs/durable/reliability/multi-instance): Web and worker instances compete for the SAME result and heartbeat queues — each delivery lands on exactly one of them. What that means for steps with and without timeoutMs, why a persisted heartbeat doesn't re-arm a timer, and when to run a pure producer with consumers: 'never'. - **Infrastructure** - Transports - [Overview](/docs/durable/transports): How remote steps travel to workers. Transports are config-driven drivers selected by name in config/durable.ts — from the in-process memory driver for zero-infra single-process handlers, to the queue driver over @adonisjs/queue, and a broker-less SQL driver that rides the database you already run. - [Queue (@adonisjs/queue)](/docs/durable/transports/queue): The queue-backed transport driver for cross-process steps, built on @adonisjs/queue. Steps go to a per-group tasks queue; results return on a shared results queue. Run one instance engine-side, one per worker group. - [SQL (database)](/docs/durable/transports/db): A broker-less, DBOS-style transport driver — remote steps are rows in the Lucid database you already run. Workers claim tasks with an atomic, portable lease so a row is never run twice. The migration ships with @adonis-agora/durable. - [Control plane](/docs/durable/transports/control-plane): The cross-instance broadcast channel for lifecycle events and cancellation — separate from the point-to-point task transport. Omit it and the engine is local-only; pick controlPlanes.redis to fan out across every replica over Redis pub/sub, interoperable with a NestJS fleet. - State stores - [Overview](/docs/durable/stores): Where durable state lives. A config-driven StateStore with a Lucid driver that runs on Postgres, MySQL, or SQLite, an in-memory store for tests, and a migration shipped with @adonis-agora/durable. - [Lucid](/docs/durable/stores/lucid): The Lucid StateStore driver — persist runs and checkpoints to Postgres, MySQL, or SQLite through @adonisjs/lucid. The migration ships with @adonis-agora/durable; select the store with stores.lucid(). - Observability - [Dashboard](/docs/durable/observability/dashboard): The embedded operations console — a React SPA plus a JSON API mounted into your AdonisJS routes. Filter runs, live-tail a run's timeline, fix-and-replay a bad input, deliver signals/updates/task completions, pause and trigger schedules, act on runs in bulk, and read the worker fleet's health — with the whole wire contract published as OpenAPI 3.1. - [Dashboard auth](/docs/durable/observability/dashboard-auth): The console's optional session layer (dashboardAuth) — sign operators in at a built-in login page, or mint a session straight from your already-authenticated app. A signed HMAC cookie gates the pages (302 or 401) and the JSON API (401). Opt-in, additive to authorize, fails closed at boot. - [Events & interceptors](/docs/durable/observability/events-and-interceptors): The two programmatic hooks into a running engine — engine.subscribe for the lifecycle event stream (every EngineEvent type and its payload), and engine.use for onion middleware around a local step. Plus collectMetrics for a Prometheus endpoint and attachDurableDiagnostics for the diagnostics bus. - [OpenTelemetry](/docs/durable/observability/otel): One trace per run, one span per step. Bridge the engine's lifecycle events to OpenTelemetry with attachDurableOtel and see workflows in Jaeger, Grafana, or Datadog — plus distributed tracing across worker processes. - [Telescope](/docs/durable/observability/telescope): Surface workflow runs and steps inside Telescope with durableTelescopeExtension() — a Workflows dashboard with golden-signal health, current-state gauges, and recent failures, alongside your app's requests, queries, and jobs. - **Cluster** - Cluster: Split the API from the engine, run store-less thin pods, route per tenant, and share one control plane across languages. - [Topologies](/docs/durable/cluster): Run durable as a single process, split the control plane from the workers, or spread store-less "thin" pods per tenant — one config field, no code changes to your workflows. - [Roles & config](/docs/durable/cluster/roles-and-config): The role-discriminated config/durable.ts, the worker vs api entrypoints for a store-less pod, and layered tenant authentication — with store-less isolation enforced at compile time. - [Thin workers](/docs/durable/cluster/thin-workers): The @adonis-agora/durable/worker subpath — WorkerRuntime, the descriptor registry, and the turn/step runners that let a worker pod execute steps and workflow turns without ever importing Lucid or owning a state store. - [Handshake & negotiation](/docs/durable/cluster/handshake): How a mixed fleet stays version-safe — workers advertise a capability descriptor, the control plane negotiates compatibility, and work routes only to workers that can run it. Runs park blocked instead of hanging. - [Cross-ecosystem interop](/docs/durable/cluster/interop): Run Adonis, NestJS, and Python workers on one durable control plane. The BullMQ transport speaks the aviary wire byte-for-byte, so a step dispatched by an Adonis engine can execute on a Python worker and flow back. - **Cross-language** - [Python](/docs/durable/python): Python is a first-class durable runtime for Agora too. Implement steps an AdonisJS workflow calls, OR author whole workflows in Python that the Adonis engine drives — both over the same Redis wire, with the engine owning durable state. - **Operations** - Tooling - [Linting for non-determinism](/docs/durable/tooling/linting): Catch Date.now(), Math.random(), process.env, swallowed control-flow signals and direct I/O inside a workflow body at author time with @adonis-agora/durable-eslint-plugin — AST-scoped ESLint rules that know both the engine.register() function form and a BaseWorkflow class. - [Testing](/docs/durable/testing): Unit-test workflows with an in-memory engine harness, a clock you control for durable sleep, crash/flaky-step injection, assertions that read the recorded state, and a replay-CI loop (durable:export → parseRunHistory → assertReplayable) that fails the build on a determinism break — no Postgres, no Redis, no real time. - [CLI](/docs/durable/cli): Ace commands for durable — durable:work runs the store-backed worker loop, durable:worker runs a store-less thin worker, durable:runs lists runs (including the --stale view), durable:retry re-enqueues a run, durable:export captures a replay fixture for CI, and make:workflow scaffolds a workflow. - Telescope: A Telescope-style observability console — watchers, entries, and an extensible dashboard. - [Telescope](/docs/telescope): Laravel Telescope-style observability for AdonisJS — a generic capture spine records every HTTP request, every Lucid query, and every Agora diagnostics event as a queryable entry, browsable from a self-contained dashboard, with alerts and AI exception diagnosis on top. - [Getting Started](/docs/telescope/getting-started): Install @adonis-agora/telescope, configure it into your AdonisJS app, read entries back from the headless API, then layer on persistent storage, per-technology watchers, and the dashboard. - Concepts - [Capture & correlation](/docs/telescope/concepts/capture): The mental model behind Telescope — what a watcher is, the uniform Entry shape every recording produces, the generic diagnostics spine that records all library events, exception auto-capture, and how trace correlation works without coupling to @adonis-agora/context. - [Storage](/docs/telescope/concepts/storage): The TelescopeStore contract every watcher records through and the query API reads from — the config-driven driver model (the in-memory ring buffer and the SQL-backed Lucid store), the EntryQuery filter model, retention and pruning. - [Extensions](/docs/telescope/concepts/extensions): The declarative extension SPI — how a sibling library contributes navigable entry types, declarative dashboard pages (the panel IR), and server-side data providers to Telescope without forking it or shipping any React. - [Performance](/docs/telescope/concepts/performance): Why capture doesn't slow the app it observes — request recording sits in a finally block off the response path, watchers are fire-and-forget, the in-memory store is bounded, and every recording is guarded so a failing store can never break or block a hot path. - [Retention & overload protection](/docs/telescope/concepts/protection): Two core safeguards that keep Telescope bounded and self-limiting — a background pruner that deletes stale entries on a timer so the store never grows without bound, and an event-loop overload guard that pauses capture when the p99 lag crosses a threshold so Telescope can never amplify an incident. - Dashboard - [Dashboard](/docs/telescope/dashboard): Mount the Telescope console — the @adonis-agora/telescope-ui React SPA served under the same prefix and auth guard as the core JSON API + SSE it reads from the headless TelescopeService — browse entries by type, family and trace, and reach the same data programmatically. - [Dashboard auth](/docs/telescope/dashboard/auth): How the Telescope dashboard is gated — the default allow-in-dev / deny-in-prod policy, the built-in token and HTTP Basic credentials, delegating to your own app auth with an authorize hook, and the 401-vs-403 fail-closed guard behaviour. - Packages - [Packages](/docs/telescope/packages): Everything ships as one package — @adonis-agora/telescope — exposing the headless core (with config-driven memory + Lucid storage drivers) plus opt-in subpaths for per-technology watchers, the dashboard UI, alerts, and AI exception diagnosis. - [@adonis-agora/telescope](/docs/telescope/packages/core): The headless core — the request, exception and diagnostics watchers, the uniform Entry model, the TelescopeStore contract and in-memory ring buffer, the TelescopeService query API, the extension SDK, and the structural readers for context and diagnostics. - [Storage drivers](/docs/telescope/packages/storages): Telescope's config-driven storage — the in-memory ring buffer and the SQL-backed Lucid driver built into the core with the storage factory, plus the Lucid migration, JSON-text columns, integer epoch timestamps, and per-driver options. - [@adonis-agora/telescope/watchers](/docs/telescope/packages/watchers): The watchers subpath of @adonis-agora/telescope — record every Lucid SQL query (sql, bindings, duration, connection), every email sent, @adonisjs/cache hit/miss/write/delete events, outbound fetch calls, and AdonisJS logger output, each correlated to the active request trace. - [Pulse health rollup](/docs/telescope/packages/pulse): Pulse is Telescope's aggregated "at a glance" health rollup — throughput, request error rate and latency percentiles, slowest entries, slow route/outgoing/job hotspots, N+1 suspects, top exception families, cache hit rate, and load-by-user — computed on demand from stored entries and served at /api/metrics/pulse, from the headless getHealth API, and via the MCP get_health tool. - [Metrics API](/docs/telescope/packages/metrics): The programmatic analytics layer of @adonis-agora/telescope — MetricsService and the pure functions behind it (percentiles, latency histograms, throughput timeseries, trace summaries, span waterfalls, N+1 detection) exported from the main package so you can compute the same numbers the dashboard shows without going through HTTP. - [@adonis-agora/telescope/ui](/docs/telescope/packages/ui): The Telescope dashboard's read backend — a JSON API plus an SSE live-stream served from the headless TelescopeService and mounted onto your app's router behind a configurable auth guard. The dashboard page itself is the separate @adonis-agora/telescope-ui SPA, which consumes these routes. - [@adonis-agora/telescope-ui](/docs/telescope/packages/telescope-ui): The observability console SPA — a React single-page app with ten sections (overview, entries + live tail, traces & waterfall, Pulse, exception groups, live queues, live schedules, exports, CPU profiles, extension dashboards), a command palette and a light/dark theme, served by a thin AdonisJS provider under the same prefix and behind the same auth guard as the core JSON API it consumes. - [@adonis-agora/telescope/alerts](/docs/telescope/packages/alerts): Alerting subpath of @adonis-agora/telescope — detect brand-new exception families (and re-occurrences after resolve), fire on every exception (server + browser), and catch exception-rate / metric spikes from recorded entries, then fan rich alerts out to Slack, a generic webhook, the console, or any custom channel. - [@adonis-agora/telescope/ai](/docs/telescope/packages/ai): AI-assisted exception diagnosis subpath of @adonis-agora/telescope — turns an exception entry (plus its related trace entries) into a structured cause/fix/confidence diagnosis via the Anthropic Claude API, cached by exception family hash so the same error is never diagnosed twice. - [@adonis-agora/telescope/cpu_profiling](/docs/telescope/packages/cpu-profiling): On-demand V8 CPU profiling subpath of @adonis-agora/telescope — captures real Profiler.start/Profiler.stop samples via node:inspector around a request, aggregates them into a flamegraph tree, and renders it in the dashboard. - [OTel export](/docs/telescope/packages/otel): Ship recorded Telescope entries — starting with every agora:: diagnostics event — as OTLP spans and logs to a self-hosted OTel Collector, so the whole Agora ecosystem shows up in Grafana (Tempo/Loki) with zero per-lib code. - [@adonis-agora/telescope/mcp](/docs/telescope/packages/mcp): The Model Context Protocol subpath of @adonis-agora/telescope — a stateless JSON-RPC endpoint that lets a coding agent (Claude Code, Cursor, …) query the app's captured telemetry with six read tools (list entries, get entry, get trace, get waterfall, Pulse health, AI diagnose), behind the same auth guard as the dashboard. - [Client-error ingestion](/docs/telescope/packages/client-errors): A public, opt-in POST endpoint browsers report front-end errors to — recorded as client_exception entries through Telescope's normal redaction / sampling / prune pipeline — protected by a body byte cap, an in-memory per-IP token bucket, an optional authorize hook, and the overload guard's shed flag. - [Advanced / programmatic](/docs/telescope/packages/advanced): The lower-level store-decorator and helper exports of @adonis-agora/telescope — bounded redaction (redactBounded / RedactingTelescopeStore / compileRedactSpec), tail-sampling (SamplingTelescopeStore / passesSampling / resolveSampling), and the live-stream bus (EntryEvents / StreamingTelescopeStore / streamEntries) — for wiring a custom store chain by hand. - Guides - [Guides](/docs/telescope/recipes): Task-oriented recipes for Telescope — write a custom watcher, implement a custom storage backend, build a dashboard extension, shape what gets captured with tags and redaction, correlate by request context, and add AI exception diagnosis. - [Custom watcher](/docs/telescope/recipes/custom-watcher): Build your own Telescope watcher — implement the Watcher contract over the AdonisJS event emitter, record through the guarded safeRecord helper with trace correlation, and register it so it starts and stops with your app. - [Custom storage adapter](/docs/telescope/recipes/custom-storage): Implement the TelescopeStore contract against any backend — a full MongoDB-backed store covering record, get, list with every EntryQuery filter, count, prune with keepLast, and clear, plus the trace/origin resolution every store owes its callers. - [Building an extension](/docs/telescope/recipes/building-an-extension): Step-by-step — package a sibling library's observability into a Telescope extension that contributes a navigable entry type, server-side data providers, and a declarative dashboard page, then register it in config — with no React and nothing Telescope-internal. - [Tags & redaction](/docs/telescope/recipes/tags-and-redaction): Shape what Telescope captures — how tags and family hashes are assigned, how to add your own tags and grouping, how to redact sensitive values before they're recorded, and how to drop or sample noisy entries with a wrapping store. - [Request context](/docs/telescope/recipes/request-context): Correlate Telescope entries to a request, a trace, a tenant, and a user via @adonis-agora/context — how trace correlation works, how to tag entries with the authenticated user, and how to reconstruct everything that happened on one trace. - [AI exception diagnosis](/docs/telescope/recipes/ai-exception-diagnosis): Add Claude-powered root-cause diagnosis of Telescope exceptions — install and configure the @adonis-agora/telescope/ai subpath, diagnose an exception with its trace context, read the cached cause/fix/confidence, and plug in a custom diagnosis cache. - Reference - [Configuration](/docs/telescope/reference/configuration): Every configuration key across the Telescope ecosystem in one place — the core, watchers, dashboard UI, alerts, and AI packages, each with its config file, defaults, and the environment variables it expects. - Authz: DB-backed roles & permissions that feed AdonisJS Bouncer — wildcard grants, tenancy, a Lucid store and ace commands. - [Authz](/docs/authz): Bouncer-integrated, DB-backed RBAC for AdonisJS — roles, permissions, wildcard matching and multi-tenancy that plug into @adonisjs/bouncer rather than replacing it. - [Getting started](/docs/authz/getting-started): Install @adonis-agora/authz, run the migration, grant a permission and check it through Bouncer. - [Concepts](/docs/authz/concepts): Roles, permissions, wildcard matching, polymorphic users and multi-tenancy. - [The authz service](/docs/authz/service): AuthzService and the services/main singleton — can, scope, hasRole, hasAnyRole, effectiveRoles, effectivePermissions, subjectsWithRole, the super-admin resolution and the per-request permission cache. - [Roles](/docs/authz/roles): authz as the single authority on roles — the effective-role union, the reverse lookup subjectsWithRole(), the resolveRoleMembers / resolveGlobalRoleMembers seams, and superAdminRoles. - [Query scopes](/docs/authz/query-scopes): Register a scope filter for a resource so accessibleBy() constrains a collection to the rows a user may see — the scopes config key, ScopeRegistry.register, and the eq/where/whereIn/and/or DSL. - [Configuration](/docs/authz/config): The drivers-in-core config idiom — select a permission store, wire the super-admin hook, user-ref mapping and tenant resolver. - [Bouncer integration](/docs/authz/bouncer-integration): The can / hasRole Bouncer abilities backed by the store, and how to use them in controllers and Edge. - [Route middleware](/docs/authz/middleware): AuthzRoleMiddleware — an any-of route guard on the user's effective roles (global ∪ app ∪ store) or permissions, with guest/denied redirects and a host-owned onDenied hook. - [Agora integration](/docs/authz/agora-integration): Opt-in bridges to the Agora ecosystem — tenant auto-scope, the global-role bridge, event-driven provisioning, and the /authz/can endpoint. - [React / Inertia](/docs/authz/react): Client-side authorization for Inertia + React — AuthzProvider, useAuthz, useCan, the gating component, and the server-side buildAuthzShare() that pushes effective grants to the frontend. - [Lucid mixin](/docs/authz/mixin): Add assignRole / can / getRoles sugar directly to your user model. - [Roles relation](/docs/authz/roles-relation): authzRolesRelation() — the Lucid manyToMany options that join your user model to the authz roles through the authz_subject_role pivot, so a listing preloads roles instead of asking once per user. - [Ace commands](/docs/authz/commands): Manage roles and permissions from the command line. - [Testing](/docs/authz/testing): Use the memory store and the shared store contract suite to test authorization deterministically. - Media: A media library for AdonisJS — owner collections, image conversions, and column attachments on top of @adonisjs/drive. - [Media](/docs/media): A media library for AdonisJS — attach files to your entities, organize them into collections, and generate image conversions, all on top of @adonisjs/drive. The spatie/laravel-media-library feel, for Adonis. - [Getting Started](/docs/media/getting-started): Install @adonisjs/drive and @adonis-agora/media, configure the library, attach your first file to an entity, generate a conversion, and resolve URLs. - [Configuration](/docs/media/configuration): Every key on defineConfig — disk and the disks map, store and stores, imageProcessor, collections, uploads, delivery, the attachment key prefix and the diagnostics toggle — and how the provider builds the MediaManager at boot. - [Collections & Conversions](/docs/media/collections-and-conversions): Collections are the policy layer — MIME whitelist, single-file replacement, ordering, and a per-collection disk. Conversions are the image pipeline — width/height/fit/format/quality, generated eagerly or lazily and cached. - [Transformers & HLS](/docs/media/transformers): Pluggable content transformations — turn a stored media into derived artifacts (an HLS package, an extracted audio track) or pure metadata (a probe), persisted as named conversions. Ships with a mediabunny-backed HLS transformer and a metadata probe, plus an HLS-aware delivery handler. - [Attachments](/docs/media/attachments): Column attachments — the adonis-attachment style, where a file (and its image variants) lives directly on a model column as a JSON value, over the same Drive disks and image processor as the media library. - [Single-File Store](/docs/media/single-file): @adonis-agora/media/single-file — a tiny seam for avatar-style uploads, so another package can delegate 'replace this owner's one file and give me a URL' to media without taking a hard dependency on it. - Uploads - [Upload Modes](/docs/media/uploads/upload-modes): Two upload strategies over a multipart-capable disk — proxy (bytes stream through your app) and direct (the browser uploads straight to S3 via presigned multipart part URLs). MediaManager.uploads and the opt-in provider routes under /media/uploads. - [Direct Sessions](/docs/media/uploads/direct-sessions): Session-backed browser→S3 multipart uploads — media.direct persists uploadId, part size and confirmed ETags in an UploadSessionStore, so a page reload resumes instead of restarting. Presigned part URLs, collection-aware initiate, and completeDirectUploadToLibrary. - [Direct Upload Policy](/docs/media/uploads/direct-upload-policy): DirectUploadPolicy — the app-injected strategy that decides an upload's object key, what a completed upload becomes in your domain, and how failures read as HTTP. The seam that turns the built-in direct-session routes into a complete feature. - [Resumable / TUS](/docs/media/uploads/resumable-tus): Resumable, chunked uploads over the tus 1.0.0 protocol — media.resumable and the opt-in TUS routes under /media/uploads/tus, backed by a pluggable UploadSessionStore (in-memory + Lucid) that persists offset/length/metadata/expiry so a dropped connection resumes. - Storage - [S3 Disk](/docs/media/storage/s3-disk): The bundled disks.s3() driver — an S3 (or S3-compatible) disk with extended operations (copy/move/deleteMany/list/size/stat), native multipart, and presigned URLs. The AWS SDK is an optional, lazily-imported peer. - [Delivery](/docs/media/delivery): A configurable read strategy — public URL, signed URL, or streaming the bytes through your app — plus the framework-agnostic MediaDeliveryHandler you mount behind your own auth. - React Client - [React Client](/docs/media/react): @adonis-agora/media-react — a React hook (useMediaUpload), a headless-friendly MediaUploader component, and a framework-free browser upload client (createMediaUploadClient) that speak the provider's actual upload contract across TUS, direct-S3 multipart, and proxy strategies. - [Upload Client](/docs/media/react/client): The full MediaUploadClient surface — the three upload strategies plus the session primitives underneath them, the injectable part transport, typed MediaHttpError, and the custom TUS metadata that reaches your server through parseTusMetadata. - [Console Launcher](/docs/media/react/console-launcher): Open the media console from your own app in three tiers — the bare mintMediaDashboardSession / openMediaDashboard functions, the useOpenMediaDashboard hook, and the drop-in OpenMediaDashboardButton. Plus ConsoleSessionError and why the redirect trap matters. - Dashboard - [Dashboard](/docs/media/dashboard): The management console that ships inside @adonis-agora/media — a React SPA plus a JSON API to browse buckets, inspect media records, watch resumable uploads, upload objects, and copy/move/delete across buckets, over the real disk and session-store surfaces. - [Console Authentication](/docs/media/dashboard/authentication): The built-in session-cookie login for the media console — Mode A mints a session from your app's own auth, Mode B accepts credentials at a login screen. Plus the exported signing helpers and how the guard slides a live session forward. - [Collections View](/docs/media/dashboard/collections): The cross-owner MediaStore.list — a cursor-paginated, filterable listing of media-library records across every owner (newest first), for management and console reads. Backs the dashboard's Collections view. - [Programmatic API](/docs/media/dashboard/programmatic): DashboardService, DashboardError, MediaManagerLike and the JSON contract types — the console's logic as a plain, framework-free object you can call from your own routes, plus the response shapes shared by server and SPA. - [Stores & Processors](/docs/media/stores-and-processors): The three pluggable seams behind the library — the MediaStore (in-memory + Lucid, with a published migration), the ImageProcessor (sharp), and the Disk contract that reuses @adonisjs/drive. Plus how to write your own. - Integrations - [Telescope](/docs/media/integrations/telescope): mediaTelescopeExtension — a first-class @adonis-agora/telescope extension that adds a "Media" overview dashboard (uploads, storage operations, image conversions) built from the agora:media:* diagnostics events. Telescope stays an optional, never-imported peer. - [Errors](/docs/media/errors): Every error class @adonis-agora/media exports, with its stable code, when it is thrown, and which properties it carries — so you can branch on a code instead of a message string. - [Testing](/docs/media/testing): Drive the media library in tests with the in-memory doubles from @adonis-agora/media/testing — InMemoryMediaStore, InMemoryDisk + inMemoryDiskResolver, InMemoryUploadSessionStore, FakeImageProcessor and FakeTransformer — no disk, no database, no sharp, no media engine. - [Roadmap](/docs/media/roadmap): What @adonis-agora/media covers today — resumable/tus uploads, direct S3 presign, an S3 disk, a React client, transformers and an embedded console — and what is still intentionally deferred (more stores, richer conversions, collection reordering). - Filter: A typed query-param filter language for Lucid — operators, defineFilter classes, offset & cursor pagination, relations via whereHas, full-text (tsvector) and vector-similarity search, and a typed client with codegen. - [Filter](/docs/filter): A typed query-filter language for AdonisJS — turn Spatie/JSON:API query strings into safe, allow-listed Lucid queries, with a typed client builder for the front-end. - [Getting Started](/docs/filter/getting-started): Add declarative query filtering to an AdonisJS project in minutes — install, declare a filter next to your model, apply it in a controller, and build the matching query string on the front-end. - Guides - [Controllers](/docs/filter/guides/controllers): Wiring a filter into AdonisJS controllers — the shape of a list endpoint, per-request policies, forced scopes a client cannot relax, strict mode and error handling, and response shapes. - [Filter Classes](/docs/filter/guides/filter-classes): The class-authoring form — a method per request key with the query builder on this.$query, a setup() scope the client cannot relax, constructor injection through the IoC container, and the pagination resolved for you. - [Decorators](/docs/filter/guides/decorators): Bind a filter method to the request keys it answers with @filterFor, and declare a model's filterable, sortable and searchable columns where the columns live. - [Lucid Integration](/docs/filter/guides/lucid): How a filter reaches SQL — the builder stays yours, pagination is resolved rather than run, distinct projections for facet endpoints, and the structural contract that makes all of it work on any Lucid builder. - [Operators](/docs/filter/guides/operators): The full operator set — 22 operators, SQL-symbol aliases, the Spatie/JSON:API wire format, AND/OR composition, and how each maps to Lucid. - [Filter Config](/docs/filter/guides/filter-config): The FilterConfig policy object — allow-listing filterable, sortable and searchable columns, bounding page size, and choosing between dropping and rejecting a disallowed field. - [Custom Backends](/docs/filter/guides/custom-backends): One class style over any backend — BaseFilter with a draft instead of a Lucid builder, driven by applyCustomFilter. - [Group By Count](/docs/filter/guides/group-by-count): The pickers' query — distinct values of one field with counts, over Lucid GROUP BY or a custom adapter. - [Relations](/docs/filter/guides/relations): Filtering across Lucid relationships — dotted paths that become whereHas subqueries, filtering the rows you preload, and sorting by a relation aggregate. - [Validation](/docs/filter/guides/validation): Built-in structural validation of column filters, the InvalidColumnFilterError, layering VineJS on parsed input, and turning failures into HTTP responses. - [Provider & Macros](/docs/filter/guides/provider): The optional @adonis-agora/filter provider registers chainable Lucid query-builder macros — applyFilterFromRequest and filterPaginate — so a model query can filter and paginate inline without importing a free function. - [Client Builder](/docs/filter/guides/client): @adonis-agora/filter-client — a zero-dependency, framework-agnostic filter query builder, its typed variant, the reactive store contract, and TanStack Table sync. - [Testing](/docs/filter/guides/testing): Unit-testing a filter spec against the shipped recording mock, asserting the allow-list and the server scope, and end-to-end Japa tests against a real database. - Definitions - [Defining Filters](/docs/filter/definitions): defineFilter + applyFilterFromRequest — a declarative, reusable filter definition (filterable/sortable allow-lists, relation whitelist with a depth cap, tenant scope, and server defaults) applied to a Lucid query in one call. - [Relation Filtering](/docs/filter/definitions/relations): Declaratively whitelist relations in a FilterSpec — a dotted request field (relation.column) is translated into a nested Lucid whereHas subquery, bounded by a depth cap. - [Computed Fields](/docs/filter/definitions/computed): Declare virtual/computed columns on a filter spec — a dev-authored SQL expression (string or correlated-subquery function) that becomes filterable and sortable exactly like a real column, with the client value always parameterized. - [To-many Aggregates](/docs/filter/definitions/aggregates): Filter and sort by a to-many relation's aggregate — posts.$count, posts.$sum.views, $avg / $min / $max — synthesised as correlated-subquery computed fields from a Lucid model's relation metadata. - [Field Aliases](/docs/filter/definitions/aliases): Remap a client-facing field name to a different target column before allow-listing — decouple the public query vocabulary from your schema, without cascading or cycles. - [Request Input](/docs/filter/definitions/request-input): The input layer — parseSpatieRequest for the full Spatie/JSON:API shape (includes, sparse fieldsets, cursor pagination), resolveInputFromRequest for where input is read from, and normalizeInput for key casing. - Pagination - [Cursor Pagination](/docs/filter/pagination): Keyset (cursor) pagination — applyCursor / applyCursorFromRequest build a stable, seek-based page from the sort + a primary-key tiebreaker; buildCursorPage assembles the page and its opaque forward/backward cursors. - Search - [Search](/docs/filter/search): Three search modes — portable ILIKE (default), Postgres tsvector full-text search (keyword matching), and pgvector embedding-similarity ordering. What each does and when to reach for it. - [Full-Text Search](/docs/filter/search/full-text): Postgres tsvector keyword search — route the request search term through websearch_to_tsquery / @@ against a tsvector column or to_tsvector-wrapped text columns, with optional ts_rank relevance ordering. - [Vector Similarity](/docs/filter/search/vector-similarity): pgvector embedding-similarity ordering — rank rows nearest-first by distance between a stored embedding column and a query embedding, with a configurable metric, max-distance threshold, and top-K truncation. - Codegen - [Client Codegen](/docs/filter/codegen): Generate a typed @adonis-agora/filter-client builder from a FilterSpec — generateFilterClient (pure string transform) and the make:filter-client ace command that writes the modules to disk. - Testing Utilities - [Testing Utilities](/docs/filter/testing): The @adonis-agora/filter/testing subpath — a shipped MockQueryBuilder recorder that satisfies QueryBuilderLike, so you can unit-test filter definitions (including relation whereHas subqueries and raw search/vector SQL) without a database. - Agent: A governed, durable-ready AI agent for AdonisJS — streaming chat, tool-calling, HITL, quota/cost accounting and multi-agent delegation. - [Agent](/docs/agent): A governed, durable-ready AI agent for AdonisJS — streaming chat, tool-calling, fail-closed governance, human-in-the-loop approvals, and multi-agent delegation. One agent loop, two runners. - [Getting Started](/docs/agent/getting-started): Run your first governed agent in an AdonisJS app — install, configure a model and store, run the migration, define a tool, and stream a chat over SSE. - **Guides** - Concepts - [The agent loop](/docs/agent/concepts/agent-loop): The provider-agnostic agent turn — the model→tools→approval→model state machine, the hooks seam that makes it replay-safe, and the inline vs durable runners that drive it. - Authoring - [Tools](/docs/agent/authoring/tools): Give the agent things to do — @AiTool classes and defineTool functions, discovered from app/agent_tools, with read/action kinds, Standard Schema inputs, and role/ability gating. - [Personas & agents](/docs/agent/authoring/personas-and-agents): Shape one assistant with personas (prompt + tool allow-list), or run several named agents that hand work to one another through delegatesTo multi-agent delegation. - [Attachments & multimodal](/docs/agent/authoring/attachments): Let users attach images and PDFs to a message so a vision-capable model sees them natively — the MessageAttachment shape, the attachment-staging SPI, and the optional POST /agent/attachments upload route. - [Governed SQL (data satellite)](/docs/agent/authoring/data-satellite): Give the agent a single, fail-closed read-only SQL tool — dataTool validates one SELECT, enforces a table allow-list, rewrites in a tenant scope, injects a LIMIT, and truncates oversized results. - [Asking the user](/docs/agent/authoring/elicitation): A structured question set the agent puts to the user before it works — and parks on. - [Input and output processors](/docs/agent/authoring/processors): A seam on each side of the model call — rewrite the prompt going out, gate the answer coming back. - [Structured output](/docs/agent/authoring/structured-output): Constrain a turn's answer to a schema, and get the validated value back alongside the prose. - [Transient tool retries](/docs/agent/authoring/transient-retry): Retry a tool's own invocation in place when it hits a classified-transient DB error (deadlock, lock-wait timeout, serialization failure) — bounded, replay-safe, and on by default, while business failures stay one-shot. - Retrieval (RAG) - [RAG & retrieval](/docs/agent/retrieval/rag): Ground the agent in your own corpus — the Retriever, EmbeddingProvider, and Reranker SPIs, the memory and pgvector retrievers, and always-on "inject" retrieval that folds cited passages into the system prompt. - [pgvector store](/docs/agent/retrieval/pgvector): The production RAG store — cosine/L2/inner similarity over a vector(N) column on Postgres + pgvector, through @adonisjs/lucid, with a published migration and safe identifier handling. - [Qdrant store](/docs/agent/retrieval/qdrant): A managed vector database as the RAG backend — collection provisioning, payload-filter ACLs, batched upserts, and the metric handling that keeps scores comparable with pgvector. - [Corpus lifecycle](/docs/agent/retrieval/corpus-lifecycle): Keeping an index correct after ingestion — relabel metadata without re-embedding, enumerate what is indexed, delete by filter, and the guard that refuses to wipe the corpus. - [RAG media ingestion](/docs/agent/retrieval/media-ingestion): Auto-index uploaded files into the agent's RAG store — mediaRagIngestion bridges an @adonis-agora/media upload.complete event through text extraction, chunking, and embedding, tagged per tenant/owner. - [Generative UI](/docs/agent/generative-ui): Let a tool stream a typed UI component — a chart, a card, a form — into the reply instead of (or alongside) plain text, via ctx.emitComponent, the text|component stream frame, and the component SSE frame. - Governance - [Authorization](/docs/agent/governance/authorization): The fail-closed governance model — the DefaultToolAuthorizer (ADMIN-only, role intersection), the offered-and-invoke double check, and the ActorResolver identity seam that never fabricates a caller. - [Authz (Bouncer) adapter](/docs/agent/governance/authz-bouncer): Swap the ADMIN-only role gate for ability-based authorization — the @adonis-agora/agent/authz adapter checks each tool's declared ability through @adonis-agora/authz (Bouncer), tenant-scoped and fail-closed. - [Quota & cost](/docs/agent/governance/quota-and-cost): Meter agent spend — a fail-closed daily token quota checked before the model runs, a per-turn usage ledger with real or estimated cost, and the model pricing table. - [Governance read-model](/docs/agent/governance/read-model): The read/analytics side of the agent — spend, usage trend, run lifecycle, tool stats, reliability, and a cross-thread approvals inbox over the persisted tables, exposed as /agent/governance/* routes. - [Governance console](/docs/agent/governance/dashboard): The bundled React console — nine sections over the governance read-model, an approvals inbox that decides, a pricing editor, and the gate that decides whether it mounts at all. - [Evals and scorers](/docs/agent/governance/evals): Score the answers your agent already gave — including the HITL rejections your operators produced for free. - [Telescope "Agent" tab](/docs/agent/governance/telescope): A first-party Telescope extension — nine sections spanning live activity, spend, run reliability, governance and RAG, plus the provider/section API for adding your own panels. - Durability - [The durable runner](/docs/agent/durability/durable-runner): Run each turn as a replay-safe @adonis-agora/durable workflow — memoized LLM/tool steps, HITL approval that suspends on a signal and survives restarts, and delegation as a tracked child workflow. One config flag. - State store - [Lucid](/docs/agent/stores/lucid): Persist threads, messages, tool calls, and token usage to Postgres, MySQL, or SQLite through @adonisjs/lucid — the six agent tables, the published migration, and the in-memory twin for tests. - **Operations** - [Streaming & HTTP](/docs/agent/streaming-and-http): The eleven core /agent routes, the five optional surfaces, the SSE envelope, human-in-the-loop approve/reject, and re-attaching to a live run. - [Browser client & React](/docs/agent/browser-client): The framework-agnostic SSE client and the useAgentChat React hook shipped in the package — streaming chat, automatic resume across a dropped connection, component frames, and the HITL calls the client deliberately leaves to you. - [MCP server](/docs/agent/mcp): Expose your governed tool registry to Claude, Cursor, and any other MCP client over Streamable HTTP — with OAuth or API-key auth, fail-closed by default, and the same role checks the agent loop applies. - [MCP client](/docs/agent/mcp-client): Import an external MCP server's tools into this deployment's own ToolRegistry — HITL-gated by default, namespaced, schema-validated, and screened for a pattern that can stall the process. - [Multi-replica streaming (Redis)](/docs/agent/redis-streaming): Swap the in-process token sink for the Redis transport so any pod can serve any run's SSE stream — the same byte-for-byte envelope, fanned across replicas over Redis pub/sub plus a replayable list. - [Diagnostics & tracing](/docs/agent/diagnostics): The eight lifecycle events and four span channels the agent publishes — their exact names and payloads, what is deliberately redacted, and how to subscribe. - [Testing](/docs/agent/testing): Drive the agent offline — the FakeModelProvider and echoScript, and in-memory doubles for the store, sink, quota, and governance queries, all from @adonis-agora/agent/testing. - **Reference** - [Configuration reference](/docs/agent/config-reference): Every field of AgentConfig — the shape of config/agent.ts — with its type, default, and behavior. - [Programmatic API](/docs/agent/programmatic-api): Run a turn from a job, a queue, or a command instead of an HTTP request — the AgentService facade, what it does and does not enforce, and passing model settings through to the AI SDK. - AuthKit: An AdonisJS OIDC/OAuth2 Authorization Server kit, OIDC client adapter, and React frontend ergonomics. - **Getting Started** - [AuthKit](/docs/authkit): An OIDC Authorization Server and client kit for AdonisJS. - [Getting Started](/docs/authkit/getting-started): Stand up an Authorization Server, wire a relying party, and read the user in your controllers via ctx.auth. - [Quickstart](/docs/authkit/starter): Two end-to-end walkthroughs — everything in one app, or a standalone IdP with separate client apps. - [Deployment Topologies](/docs/authkit/topologies): Run a dedicated IdP, or embed the provider inside an existing app. - **Feature Guides** - [Personal Access Tokens](/docs/authkit/personal-access-tokens): Issue, list, and revoke PATs; validate them by introspection. - [Impersonation](/docs/authkit/impersonation): Act as another user via RFC 8693 token-exchange — the IdP grant, the kill switch, and the relying-party session glue. - [MFA / TOTP](/docs/authkit/mfa): Authenticator enrollment, the login challenge, and recovery codes. - [WebAuthn / Passkeys](/docs/authkit/webauthn): Passkeys as a second factor — registration and the login challenge. - [Passwordless](/docs/authkit/passwordless): Magic-link login, six-digit email codes, passwordless sign-up, and passkey-first sign-in — without a password. - [Refresh Tokens](/docs/authkit/refresh-tokens): Proactive refresh and rotation, handled by the client middleware. - [Back-Channel Logout](/docs/authkit/back-channel-logout): OIDC Back-Channel Logout — server-to-server session termination. - [Account Linking](/docs/authkit/account-linking): Link OAuth provider identities (Google, GitHub) to one account. - [Dynamic Client Registration](/docs/authkit/dynamic-registration): RFC 7591/7592 — register OIDC clients at runtime. - [Device Flow](/docs/authkit/device-flow): RFC 8628 — the OAuth 2.0 Device Authorization Grant for input-constrained devices. - [Account Lockout](/docs/authkit/account-lockout): Progressive per-email lockout, complementary to IP rate-limiting. - [Organizations](/docs/authkit/organizations): Multi-tenancy — organizations, members, invitations, and per-org token claims. - [Compliance (LGPD / GDPR)](/docs/authkit/compliance): Account deletion with cascade, data export, verified-email gate, verified email-change flow, and security notifications. - [Adopting an Existing User Table](/docs/authkit/adopting-existing-users): Point AuthKit at the `users` table you already have — without copying a single row. - [Passwords & Migration](/docs/authkit/passwords-and-migration): Password policy, HIBP breach detection, lazy rehash, legacy hash support, pepper, history, expiration, and the users:import command. - [Runtime Settings](/docs/authkit/settings): Database-driven runtime configuration — the setting-key catalogue, precedence and config locks, the table, the CLI, and org-scoped keys. - [Config Locks](/docs/authkit/config-locks): Declaring a policy in config/authkit.ts locks it against runtime edits — how the lock works, which keys it covers, and what an operator sees when it holds. - [Customizing auth](/docs/authkit/customizing-auth): Task-oriented recipes for bending AuthKit's behaviour — route guards, role gating, where roles come from, user mapping, custom screens, emails, account stores, events, and token resolution. - [Security](/docs/authkit/security): Rate-limiting, audit logging, bot protection, RP-initiated logout, JWT access tokens, key rotation, and mail hooks. - **Frontend** - [React (Frontend)](/docs/authkit/react): useAuth, gating components, permission checks, headless hooks, and the passkey tiers of @adonis-agora/authkit-react. - [React Components](/docs/authkit/components): Pre-built, themeable components — buttons, profile and organization cards, the interaction forms, PasskeyButton, CanPermission, and KeyRotation. - [Typed Client & TanStack Query](/docs/authkit/data-fetching): useResource, createAuthkitClient, AuthkitClientProvider, query/mutation hooks, query keys, and error handling for the admin and account APIs. - [Host-owned account screens](/docs/authkit/headless-account): Run organizations, TOTP and passkeys from your own UI — the JSON mirror of the /account console, screen by screen. - **Reference** - [Host Kit](/docs/authkit/host-kit): Mounting the routes, AuthHostOptions, the config-vs-argument precedence rule, the render seam, branding, and ejecting. - [Client](/docs/authkit/client): Wire a relying party with @adonis-agora/authkit-client. - [Native @adonisjs/auth](/docs/authkit/adonis-auth): Make ctx.auth.user, middleware.auth() and the Bouncer work over an AuthKit session. - [Bring your own IdP](/docs/authkit/byo-idp): Use AuthKit's client toolkit and React SDK against any OIDC-compliant identity provider — Keycloak, Auth0, Okta, Entra — without running authkit-server. - [Account Store](/docs/authkit/account-store): The AccountStore contract, its twelve optional capabilities, the Lucid default, and the model mixins. - [Resolvers](/docs/authkit/resolvers): jwt, pat, and opaque — how a request becomes an Identity. - Keystore vaults - [Keystore vaults](/docs/authkit/keystore-vaults): Where the managed JWKS signing keystore is persisted — every jwks.store driver, its fields and defaults, and the three cloud secrets-manager companion packages. - [AWS Secrets Manager](/docs/authkit/keystore-vaults/aws): Persist the managed JWKS signing keystore in AWS Secrets Manager with @adonis-agora/authkit-vault-aws. - [Azure Key Vault](/docs/authkit/keystore-vaults/azure): Persist the managed JWKS signing keystore in Azure Key Vault with @adonis-agora/authkit-vault-azure. - [GCP Secret Manager](/docs/authkit/keystore-vaults/gcp): Persist the managed JWKS signing keystore in Google Cloud Secret Manager with @adonis-agora/authkit-vault-gcp. - [Admin Console](/docs/authkit/admin-console): The opt-in IdP admin console — a bundled React SPA with dashboard, users, sessions, orgs, clients, signing keys, audit, and runtime settings. - [Console session & sudo mode](/docs/authkit/console-session): Reuse the console account session outside the console, and gate sensitive operations behind sudo mode and its pluggable confirmation methods. - [Admin REST API](/docs/authkit/admin-api): The machine-to-machine management API — users, clients, sessions, organizations, settings, signing keys, audit, token verify. - [Backend SDK](/docs/authkit/sdk): One typed interface, two drivers — remote (HTTP Admin API) and embedded (in-process). - [Testing](/docs/authkit/testing): Test auth flows in your host app without booting an IdP — mint real signed ID tokens with a local JWKS, fake ctx.auth, fake the account store, and build valid identities. - [Events & Webhooks](/docs/authkit/events): Observe every security event the IdP audits — via an in-process callback or an HMAC-signed webhook. - [Internationalization](/docs/authkit/i18n): Translate the host-kit screens — English by default, pt-BR built in, zero config. - [Agora integration](/docs/authkit/agora-integration): How AuthKit wires into the Agora ecosystem — diagnostics events, request context, Authz, resilience, and durable GDPR workflows. - [Observability](/docs/authkit/observability): Metrics, the OTel recorder, the JSON/dashboard routes, and a Grafana board. - [Reference](/docs/authkit/reference): The full defineConfig option tables for server and client. - [Changelog](/docs/authkit/changelog): Where to find release notes and per-package changelogs. - Collaboration: Collaborative editing (CRDT) for AdonisJS — Yjs/Automerge/edge engines, Redis presence, version control, anchored comments, codegen and React client hooks. - [Collaboration](/docs/collaboration): Real-time collaborative editing for AdonisJS — the shared document converges on its own through a CRDT, while versions, anchored comments and presence layer on top through ordinary authorized routes. - [Getting started](/docs/collaboration/getting-started): Install @adonis-agora/collaboration, write config/collaboration.ts, authorize a document, choose a storage backend, scaffold the tables, and open your first shared editor. - **Guides** - Concepts - [Concepts](/docs/collaboration/concepts): The four ideas the library is built on — the document as the unit of everything, convergence as a property of the data structure, one permission seam enforced on both paths, and the line between CRDT state and ordinary data. - [CRDTs](/docs/collaboration/concepts/crdt): Why a conflict-free replicated data type removes the conflict instead of resolving it, what Yjs and Automerge each model, and the three consequences that show up in your application code. - [Documents](/docs/collaboration/concepts/documents): How a document name becomes an engine, an authorization rule and a row — pattern matching with typed params, engineFor, the resolution order, and why names never travel as path segments. - [Authorization](/docs/collaboration/concepts/authorization): The permission seam — why a WebSocket needs a token endpoint, how the same authorize callback guards both doors, what fail-closed means in practice, and which of the three permissions the library actually enforces. - [Versions](/docs/collaboration/concepts/versions): Named checkpoints over a live document — how a version is created, listed, restored into the running session and diffed, and why Yjs snapshots and Automerge's change graph answer the same API differently. - [Comments](/docs/collaboration/concepts/comments): Comments anchored to a place inside a document — the three anchor kinds, what a space is for, the create/resolve/remove lifecycle, and why comments are relational data rather than CRDT state. - [Presence](/docs/collaboration/concepts/presence): Who is in this document right now — peer-to-peer awareness for live cursors, a Redis-backed roster that spans Node instances, and the different questions each layer can answer. - Engines - [Engines](/docs/collaboration/engines): The CRDT backend behind a document — what a driver owns, how Yjs, Automerge and the edge engines compare, how a document picks one, and what changes in your code when it does. - [Yjs (Hocuspocus)](/docs/collaboration/engines/yjs): The default engine — an embedded Hocuspocus server sharing the Adonis HTTP port, y-protocols over WebSocket, shared types for text and canvases, awareness for live cursors, and snapshot-based versions. - [Automerge](/docs/collaboration/engines/automerge): A JSON-like CRDT document with a native change graph — the wire protocol, the dedicated useAutomergeDoc hook, why it cannot back a Y.Doc, and the single-instance constraint. - [Edge (PartyKit / PartyServer)](/docs/collaboration/engines/edge): Move the WebSocket to Cloudflare Durable Objects — how the worker, the signed token and the /state endpoints divide the work, what you have to own, and when the latency is worth it. - **Backend** - REST routes - [REST routes](/docs/collaboration/routes): The ten built-in endpoints — the full request and response reference, how they are auto-registered, the three levels of control over them, and why every document name travels as a query or body field. - [Token flow](/docs/collaboration/routes/token-flow): How a browser gets a credential a WebSocket can carry — the five steps, what the signed token contains, where its key comes from, what happens when one expires, and how the reconnect loop turns expiry into revocation. - [Binary state](/docs/collaboration/routes/state): The two machine-to-machine endpoints that carry a document's raw bytes — who calls them, why the write path is secret-authenticated rather than session-authenticated, and what to use them for. - Storage - [Storage](/docs/collaboration/storage): The one persistence seam every driver shares — what CollaborationStorage is responsible for, the three built-in implementations, and how to pick between them. - [Lucid storage](/docs/collaboration/storage/lucid): The production backend — how it resolves the connection, the three tables and their columns, what the published migrations do, and what actually needs backing up. - [Custom storage](/docs/collaboration/storage/custom): Implement CollaborationStorage yourself — the ten methods, the contracts that are easy to get subtly wrong, and a worked S3-backed example. - Codegen - [Codegen](/docs/collaboration/codegen): Two ace commands and a generated registry that keeps document names, spaces and anchors typed on both sides of the wire — derived from the files on disk instead of a list you maintain. - [Commands](/docs/collaboration/codegen/commands): collaboration:init, collaboration:prune and make:collab-document — what each one writes, every flag, and the generated document-types file explained line by line. - [Typed registry](/docs/collaboration/codegen/documents-registry): The generated .adonisjs/collaboration/documents.ts — how the union is derived from disk, when it refreshes, what it looks like when empty, and how to use it on both sides. - **Client** - Client - [Client hooks](/docs/collaboration/client): The React package — the provider and its config, the hooks and which one to reach for, why the client never hard-codes an engine, and how sessions are reference counted. - [Sessions](/docs/collaboration/client/sessions): One Y.Doc and one transport per document name — how a session starts, what each status means, how reconnection with fresh tokens works, and why the doc reference is stable across renders. - [Comments & versions](/docs/collaboration/client/comments-and-versions): The two REST-backed hooks — their full shape, which operations update optimistically and which refetch, error handling, and why they keep working while the socket is down. - [Editors](/docs/collaboration/client/editors): useCollabEditor and the adapter seam — how a scene maps into a document key, the three built-in adapters, writing your own, and when to drop down to the raw Y.Doc instead. - **Operations** - Advanced - [Advanced](/docs/collaboration/advanced): The two escape hatches — replacing the built-in REST surface with your own controllers, and binding a rich-text editor directly to the shared document. - [Custom controllers](/docs/collaboration/advanced/controllers): Take over the HTTP surface without losing the library's token semantics — the three levels of control, a complete working controller, and the authorization you take over along with it. - [Tiptap collaboration](/docs/collaboration/advanced/tiptap-integration): Turn a single-user Tiptap editor into a shared one — the provider, the shared Y.Doc, remote cursors, the undo trap, and what the saved document actually looks like. - [Testing](/docs/collaboration/testing): Prove the parts that actually break — that authorize denies, that a version snapshot is the version's, that the client survives a remount, and that a storage failure is reported — using in-memory storage, fake transports and no server. - [Production](/docs/collaboration/production): The operational checklist — why documents are process-bound and what sticky routing has to guarantee, tuning the debounce against data loss, Redis presence, the failure stream, shutdown, secrets, growth and backup. - [Troubleshooting](/docs/collaboration/troubleshooting): The symptoms that actually happen — stuck connections, silent divergence, disappearing edits, empty presence, restores that do nothing — and how to tell the causes apart quickly. - **Reference** - [API reference](/docs/collaboration/api-reference): Every config option, manager method, exported helper, type, route and client hook — from source. - Payments: Multi-gateway payments and Cashier-style billing for AdonisJS — 18 gateways behind one driver contract, with invoice emission and method-based routing. - [Payments](/docs/payments): Multi-gateway payments and Cashier-style billing for AdonisJS — 18 gateways behind one driver contract, across Brazil, Europe, North America, Latin America and India, with invoice emission, method routing and webhook-driven business logic. - [Getting started](/docs/payments/getting-started): Install @adonis-agora/payments, configure a gateway, register webhooks and make your first charge in about five minutes — with no migration to run. - **Guides** - Concepts - [Concepts](/docs/payments/concepts): The four ideas the library is built on — money is an integer, the gateway is behind one contract, a charge is a promise until the webhook, and the ledger is what makes trusting the webhook safe. - [Money](/docs/payments/concepts/money): Why every amount is an integer of the smallest currency unit, where the decimal conversion lives, how currency is resolved, and the arithmetic rules that keep a bill from being off by a cent. - [Routing](/docs/payments/concepts/routing): How a payment method becomes a gateway — the driver contract, the manager's three resolution rules, the capability checks that fail early, and why the SDKs load lazily. - [The payment lifecycle](/docs/payments/concepts/lifecycle): From charge to revenue — what a PENDING payment actually is, the six things the webhook route does in order, the ten normalized event types, and how externalReference routes a confirmation back to your row. - [Idempotency](/docs/payments/concepts/idempotency): Why gateways redeliver, what the ledger guarantees and what it does not, why the event is recorded before any work runs, how a failed event is retried, and where your own inner guard belongs. - [Configuration](/docs/payments/configuration): The config/payments.ts reference — named providers built with lazy factories, method routing with capability checks, the invoice section, and the billing layer (who owns the schema, how a webhook is processed, where business handlers live). - Providers - [Providers](/docs/payments/providers): The gateways with a built-in driver — what each one accepts, how its webhooks are authenticated, what externalReference maps to, and which operations it simply does not expose. - **Brazil & LatAm** - [Asaas](/docs/payments/providers/asaas): The Brazilian workhorse — Pix, boleto, card and debit, native recurring billing and NFS-e, with externalReference propagated to every installment. - [AbacatePay](/docs/payments/providers/abacate): Pix and boleto, no card. HMAC-SHA256 webhooks and a BRL-only, decimal-reais API. - [Woovi (OpenPix)](/docs/payments/providers/woovi): Pix Automático and Pix charges, RSA-SHA256 webhooks, correlationID routing — and the operations its API does not expose. - [Pagar.me](/docs/payments/providers/pagarme): Stone's Brazilian gateway on the v5 Core API — orders and charges over Pix, boleto and card, native subscriptions, and integer centavos end to end. - [PagBank](/docs/payments/providers/pagbank): PagSeguro's Orders API v4 — Pix, card and boleto in integer centavos, one order id to reconcile on, and a webhook check that is not an HMAC. - [Efí](/docs/payments/providers/efi): Efí's Pix API — the gateway that needs a client certificate before it will even issue you a token, and what that means for how you configure it. - [InfinitePay](/docs/payments/providers/infinitepay): CloudWalk's Brazilian checkout — a redirect-only driver, because the payment link API is the only one InfinitePay documents. charge(), refunds, customers and subscriptions throw. - [Mercado Pago](/docs/payments/providers/mercadopago): Pix, boleto and card across seven Latin American countries — multi-currency, decimal amounts, and notifications that carry an id and nothing else. - **Global** - [Stripe](/docs/payments/providers/stripe): Cards, Pix and boleto on a Brazilian account, hosted invoices, and the Idempotency-Key header — the multi-currency default of the four. - [Adyen](/docs/payments/providers/adyen): Checkout API v71 — stored-token card charges, Pay by Link, HMAC-signed webhooks, and no customer, subscription or read-back endpoint to pretend about. - [PayPal](/docs/payments/providers/paypal): Orders v2 and Subscriptions v1 over OAuth2 — a wallet, so checkout is the entry point, and webhook verification is a round trip to PayPal. - [Mollie](/docs/payments/providers/mollie): European gateway on api.mollie.com/v2 — cards and a hosted page in any currency, native subscriptions, and a webhook that tells you nothing until you fetch it. - [Razorpay](/docs/payments/providers/razorpay): India's dominant gateway — Orders and Payments in integer paise, native subscriptions, and a hex HMAC on every webhook. - [Square](/docs/payments/providers/square): Square Connect v2 — location-scoped, integer minor units, an idempotency key in the body, and a webhook signature that covers your own URL. - **SaaS & merchant of record** - [Paddle](/docs/payments/providers/paddle): Merchant of record on the Billing (v2) API — hosted checkout only, string-cents money, and subscriptions Paddle creates for you. - [Lemon Squeezy](/docs/payments/providers/lemonsqueezy): Merchant of record on a JSON:API v1 API — hosted checkout only, money already in cents, and a test mode that lives in the API key. - [Polar](/docs/payments/providers/polar): Merchant-of-record billing for software — Polar is the seller of record and handles sales tax, so there is no direct charge endpoint and every purchase starts at a hosted checkout. - [Dodo Payments](/docs/payments/providers/dodo): Merchant-of-record billing for SaaS — cards worldwide plus Pix in Brazil, with every charge bound to a product you created in Dodo. - [Webhooks](/docs/payments/webhooks): How the mounted webhook route validates the signature, de-duplicates redeliveries, syncs the billing tables, and runs your business logic — folder handlers, billing.handlers, diagnostics events, and durable dispatch. - [Client polling](/docs/payments/client): The browser-facing status endpoint and the React hook that polls it — waiting for a Pix or boleto to settle without hand-writing the loop, and without handing one customer's payment to another. - [Billing](/docs/payments/billing): The Cashier-style subscription layer — billable Lucid mixins, the billing tables, an idempotent webhook processor that keeps local rows in sync with the gateway, and durable-backed dispatch. - [Invoices](/docs/payments/invoices): Emit invoices attached to a charge or subscription, through an invoice provider that is fully independent of the payment gateway. - **Extending** - [Custom providers](/docs/payments/custom-providers): Write a custom payment or invoice provider as a plain config factory, using the exported building blocks — httpRequest, toDecimal, emitInvoiceIfRequested, ensureCustomer, webhook security helpers. - **Operations** - [Dashboard](/docs/payments/dashboard): The embedded billing console — a React SPA plus the JSON API it runs on, mounted into your AdonisJS routes. Lead with what needs attention today, read revenue and subscriptions, find one payment by your own reference, and refund, retry or close a dispute from the same page. - [Diagnostics](/docs/payments/diagnostics): Every payments event on the @adonis-agora/diagnostics bus — the gateway-action, business and debug layers, the structural emit slot, and debugging one payment in Telescope. - [Production](/docs/payments/production): The operational checklist — webhook secrets that must not be optional, choosing a dispatcher, responding fast, sandbox flags, reconciliation, what to watch, and the deploy-day failure modes. - [Troubleshooting](/docs/payments/troubleshooting): The symptoms that actually happen — webhooks returning 400 or 500, handlers that never run, double grants, routing errors, missing invoices, a schema that upgraded halfway — and how to tell the causes apart quickly. - Patterns - [Patterns](/docs/payments/patterns): A cookbook of the flows this library exists for — Pix and subscriptions per gateway, where business logic lives, metered billing, marketplace splits, recovery, chargebacks, and reading the billing data without the bundled console. - [Pix](/docs/payments/patterns/pix): A one-off Pix charge end to end — the shared shape, then exactly what Asaas, Woovi and AbacatePay each require, what each returns, and the errors each one throws when something is missing. - [Card](/docs/payments/patterns/card): A credit card charge without the card ever reaching your server — tokenize in the browser, send the token, and let the webhook decide. The shared shape, then exactly what Stripe and Asaas each map it to, why Asaas demands the holder block, and what happens when you route credit_card to a gateway that has no cards. - [Subscriptions](/docs/payments/patterns/subscriptions): Recurring billing per gateway — tokenized cards on Asaas and Stripe, Pix Automático on Woovi, what each one needs to actually start charging, plus trials, upgrades and cancellation. - [Reacting to payments](/docs/payments/patterns/reacting-to-payments): Where the business logic lives — the convention folder, billing.handlers in the config, a diagnostics subscriber, or a durable workflow that subscribes itself — what each does when it throws, and how to make the grant safe to run twice. - [Metered billing](/docs/payments/patterns/metered-billing): Record consumption as it happens, roll it up per meter for a period, price it against per-meter rates with an included allowance, and charge the overage exactly once. - [Marketplace splits](/docs/payments/patterns/marketplace-splits): Share a charge across recipients — Asaas splits by percent or fixed amount, Woovi subaccounts keyed by Pix key — and the integer arithmetic that keeps a computed split summing to the total. - [Recovering](/docs/payments/patterns/recovering): When a payment does not go through — dunning a failed subscription charge, refunding where the gateway supports it, and reconciling the billing tables after an outage. - [Disputes](/docs/payments/patterns/disputes): A chargeback is the only event that takes revenue back after it settled, and it runs on a clock. The three moments, why actionableUntil is the field that matters, how to reach the stored dispute and submit evidence where the gateway allows it — and why the decision to fight or refund stays in your code. - [Building your own dashboard](/docs/payments/patterns/dashboard): The headless data layer behind the console — billingOverview and the store's read API, what each metric counts, and how to render cents without leaking the division into the arithmetic. - **Tooling** - [Testing](/docs/payments/testing): Test the billing layer without a gateway or a database — FakePaymentsDriver records every call, InMemoryBillingStore mirrors the Lucid models, MutableClock drives time — and the integration suite that runs the real schema against a real Postgres. - [CLI](/docs/payments/cli): The five ace commands — scaffolding a billable model and a webhook handler, printing (or creating) the webhook endpoints, reporting the health of the billing install, and reconciling the local tables with a gateway. - **Reference** - [API reference](/docs/payments/api-reference): Every config option, driver method, exported helper, domain type, event and command — from source. - [Roadmap](/docs/payments/roadmap): What is still missing — a queue dispatcher, subscription amounts on Stripe, a per-payment history, splits beyond Asaas, dispute submission beyond Stripe, and fiscal invoice reconciliation. - Sail: Docker-powered local dev services for AdonisJS — worktree-native isolated stacks, deterministic ports, and agent-friendly JSON output. - [Sail](/docs/sail): Docker-powered local dev services for AdonisJS — per-worktree isolated containers, deterministic shifted ports, and agent-friendly commands. - [Getting Started](/docs/sail/getting-started): Prerequisites, installing sail into an existing AdonisJS app, the first boot, and the everyday loop — with pointers to the deep pages. - **Guides** - [Install](/docs/sail/install): What `node ace add @adonis-agora/sail` registers, how `sail:install` derives the service list from package.json, start/env.ts and config/*.ts, and every file it writes — append-only, idempotent, Docker not required. - [Services](/docs/sail/services): The five services sail can run — images, ports, credentials, healthchecks and the env keys each one owns — plus the anatomy and merge rules of the generated compose.yml. - [Worktrees](/docs/sail/worktrees): How sail derives one compose project per git worktree, shifts every host port by a deterministic hash of the worktree name, syncs those ports into the local dot-env overrides, and cleans up stacks whose worktree is gone. - [Local domains](/docs/sail/domains): Opt-in — serve the app on a myapp.localhost / myapp.test name through a shared proxy, with per-worktree routing, subdomains and HTTPS, instead of memorising a shifted port. - [Sharing](/docs/sail/sharing): sail:share puts the worktree's running app behind a public *.trycloudflare.com URL via a cloudflared quick tunnel — for webhook callbacks, device testing and previews. - **Integrations** - [Varlock](/docs/sail/varlock): How sail detects varlock, what it appends to .env.schema (typed, tagged, @public connection coordinates), and how the per-worktree port sync stays compatible with `varlock run --` and encrypted env files. - [Agents](/docs/sail/agents): How sail behaves inside an AI coding agent — automatic JSON output, no prompts, idempotent commands with actionable failures, the managed AGENTS.md section and the shipped sail-basics skill. - **Reference** - [Commands](/docs/sail/commands): Complete reference for every sail:* ace command — arguments, flags, printed output, --json payloads, exit codes and the exact failure messages. - [Troubleshooting](/docs/sail/troubleshooting): Every failure sail can emit — the literal message, what triggered it, and the fix — grouped by Docker, ports and worktrees, env files, service shells, install detection and tunnels.