chore(1.0): prep release — README/doc red-team, admin audit attribution, CI guards

Folds all pending work into the unreleased 1.0.0 cut so every published package
ships at 1.0.0: the three pending changesets are folded into each package's curated
[1.0.0] CHANGELOG and removed, and .changeset/config.json gains
onlyUpdatePeerDependentsWhenOutOfRange so a future core minor no longer force-majors
the satellites through their peer ranges.

README & package-docs red team
- Corrected the sso/billing/backup/websockets README stability badges from
  experimental to release candidate (they contradicted docs/reference/stability.md);
  split the core/root blockquote so the satellite *packages* read release candidate
  and only the in-core opt-in features stay experimental.
- Configure-first install for billing/backup/sso; per-package corrections: sso
  migration ownership (the package owns tenant_sso_configs; migration:run
  --connection=backoffice), backup required @adonisjs/queue peer + backup_encryption
  doctor check + commands table, billing Configuration section, websockets
  onTenantEvent handler rule.
- New packages/reporting/README.md (the only satellite without one).
- core/root highlight counts corrected to match the code (28 typed events, 39 admin
  endpoints, nine doctor checks), test-count badge softened to non-numeric, and the
  reference-app/contributing snippets point at the real examples/api/docker-compose.yml.
- Fixed adjacent doc bugs surfaced in review: a nonexistent compose.test.yml
  reference, broken core examples/api/ relative links, and a backup docs flag table
  documenting a nonexistent tenant:clone --dest.

CI guards (so the above can't silently drift again)
- check-stability-versions.mjs now also asserts each README badge mirrors the matrix.
- New scripts/check-readme-links.mjs (relative + docs-site links resolve) and
  scripts/check-readme-counts.mjs (doctor=9 / admin endpoints=39 / events=28 pinned to
  source), wired into the lint-and-typecheck CI job.

Admin audit attribution
- Every mutating admin action (REST, the matching ace commands, and custom actions)
  writes an attributed, append-only admin:<resource>:<verb> audit row sourced from
  resolveAdminActor — never the request body, never a secret; best-effort, never fails
  the operation it records. Lifecycle commands gain an optional --admin=<id> flag
  (absent records the row as system).
- Deleting a non-existent webhook/feature flag now returns 404; an empty webhook PUT
  and disabling an already-disabled SSO config short-circuit with unchanged:true and
  write no row; admin OpenAPI info.version mirrors package.json; the admin sso peer is
  marked optional in the manifest.

Also folds the metrics-bundle fix (configure --with=metrics now publishes all three
metrics tables) into the core [1.0.0] changelog.

Gates: stability/links/counts/doc-paths/positioning/graduation/lockfile, lint, and
test:integrity all green. docs:build was validated earlier in this work and is not
re-run here (local memory ceiling); its dead-link gate is unaffected by these
link-neutral doc edits.

Author: Arcoders

.changeset/config.json

@@ -7,6 +7,7 @@
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",
+  "onlyUpdatePeerDependentsWhenOutOfRange": true,
   "ignore": [
     "@adonisjs-lasagna/saas-tenancy-example-api",
     "@adonisjs-lasagna/saas-tenancy-benchmarks",

.changeset/metrics-bundle-custom-and-monthly-tables.md

@@ -88,12 +88,25 @@ jobs:
       - name: Lint
         run: npm run lint
 
-      # Versions must agree with the stability labels in docs/reference/stability.md
-      # (experimental -> 0.x, release candidate/stable -> >=1.0.0). Labels are
-      # parsed from the doc, so relabeling without re-versioning fails here.
+      # Versions AND each package README's stability badge must agree with the
+      # stability labels in docs/reference/stability.md (experimental -> 0.x,
+      # release candidate/stable -> >=1.0.0; the README badge mirrors the matrix
+      # label). Labels are parsed from the doc, so relabeling without re-versioning
+      # — or without updating the README badge — fails here.
       - name: Stability labels vs. versions
         run: node scripts/check-stability-versions.mjs
 
+      # Every README link must resolve: relative links from the README's own
+      # directory (the way GitHub and npm render them) and docs-site links to a
+      # real docs page. The dead-link gate only covers links INSIDE docs/.
+      - name: README link guard
+        run: node scripts/check-readme-links.mjs
+
+      # The core + root README structural counts (doctor checks, admin endpoints,
+      # typed events) are pinned to their source of truth so they can't drift.
+      - name: README count guard
+        run: node scripts/check-readme-counts.mjs
+
       # Every satellite labeled `release candidate` must clear the graduation gate
       # (own coverage gate, ABI-versioned manifest, configure hook, CHANGELOG, doc
       # page, version >= 1.0.0), so a satellite can't carry the RC label without

.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 # @adonisjs-lasagna/saas-tenancy
 
 <p align="center">
-  <img src="assets/hero.webp" alt="Lasagna — SaaS multi-tenancy for AdonisJS 7. Every tenant lives in its own isolated PostgreSQL schema. Around it: connection routing, circuit breaking, queues, contextual logging, plans and quotas, scheduled backups with retention, read-replica routing, soft delete, and a satellite suite covering audit logs, webhooks, branding, SSO, feature flags, metrics, and Stripe billing." width="100%" />
+  <img src="assets/hero.webp" alt="Lasagna — SaaS multi-tenancy for AdonisJS 7. Every tenant lives in its own isolated PostgreSQL schema. Around it: connection routing, circuit breaking, queues, contextual logging, plans and quotas, scheduled backups with retention, read-replica routing, soft delete, and a satellite suite covering audit logs, webhooks, branding, SSO, feature flags, metrics, and multi-provider billing (Stripe, Paddle, Lemon Squeezy)." width="100%" />
 </p>
 
 [![npm](https://img.shields.io/npm/v/@adonisjs-lasagna/saas-tenancy?color=C26A4B&label=npm)](https://www.npmjs.com/package/@adonisjs-lasagna/saas-tenancy)
@@ -16,7 +16,7 @@
 
 📖 **[Full documentation →](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/)** · [Quickstart](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/start/quickstart) · [Why Lasagna](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/start/why) · [Comparison vs stancl](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/comparison) · [Release notes](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/release-notes)
 
-> **Stability: release candidate.** The isolation core is feature complete and green in CI against real Postgres and Redis, but the `stable` label is withheld until an independent security review and production mileage close. The satellites (billing, SSO, admin, backup, and the opt-in in-core features like quotas, webhooks, and metrics) are **experimental**. Full breakdown and the 1.x semver promise in the [stability matrix](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/stability).
+> **Stability: release candidate.** The isolation core is feature complete and green in CI against real Postgres and Redis, but the `stable` label is withheld until an independent security review and production mileage close. The satellite **packages** (admin, SSO, billing, backup, websockets, reporting) are **release candidate** too; the opt-in in-core features (quotas, webhooks, metrics, audit logs, branding, feature flags, impersonation) are **experimental**. Full breakdown and the 1.x semver promise in the [stability matrix](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/stability).
 
 I built this because the AdonisJS ecosystem deserved a proper multi
 tenancy foundation, and because every SaaS I touched eventually outgrew
@@ -38,16 +38,16 @@ and runs the full e2e suite against it.
 | **Schema isolation** | Each tenant gets its own `tenant_<uuid>` PostgreSQL schema, provisioned and routed automatically. |
 | **Circuit breaker** | Opossum wraps every tenant DB call; OPEN state is restored from Redis on restart so a known-down tenant DB fails fast across deploys. One bad schema can't take down the others. |
 | **Dependency resilience** | Per-dependency fail-open/fail-closed degradation policy via `ResilienceService`. Emits `DependencyDegraded` for alerting and returns a typed 503 (`DependencyUnavailableException`) when fail-closed. |
-| **Lifecycle hooks + 25 typed events** | Declarative `before` / `after` hooks wired into commands and jobs. 14 tenant/quota-lifecycle + 10 billing + 1 resilience event. |
+| **Lifecycle hooks + 28 typed events** | Declarative `before` / `after` hooks wired into commands and jobs. 18 core (tenant / quota / maintenance / resilience / metrics lifecycle) + 10 billing. |
 | **Contextual logging** | `tenantId` rides along through HTTP and queue jobs via `AsyncLocalStorage`. |
-| **`tenant:doctor`** | Ten built-in checks, `--fix` for auto-recovery, `--json` for CI, `--watch` for a live TUI. |
+| **`tenant:doctor`** | Nine built-in checks (plus `backup_recency` and `backup_encryption` when the backup satellite is installed), `--fix` for auto-recovery, `--json` for CI, `--watch` for a live TUI. |
 | **Plans and quotas** | Declarative plans, rolling counters, snapshot usage, an `enforceQuota()` middleware that returns 429 and emits `TenantQuotaExceeded`. |
 | **Scheduled backups + retention** | Tier-based intervals and `keepLast`, S3 mirror with purge awareness, idempotent cron command. |
 | **Health probes + Prometheus** | `/livez`, `/readyz`, `/healthz`, `/metrics`. No `prom-client` peer dep. |
 | **Read replica routing** | Round-robin, random, or sticky-by-tenant-id with stable connection naming. |
-| **REST admin API** | 36 endpoints + OpenAPI 3.1 spec + Swagger UI. You bring the auth middleware. |
+| **REST admin API** | 39 endpoints + OpenAPI 3.1 spec + Swagger UI. You bring the auth middleware. |
 | **Soft delete TTL** | Recycle bin pattern. `--keep-schema` on destroy, `tenant:purge-expired` on a cron. |
-| **Ten satellites** | Audit logs (append-only at the SQL level), webhooks (HMAC-signed + retries + verifier helper), quotas, feature flags, branding, SSO/OIDC, real-time WebSockets (socket.io, tenant-isolated), metrics, impersonation, and Stripe billing (idempotent webhook + dunning + metered + checkout/portal + lifecycle). All optional. |
+| **Ten satellites** | Audit logs (append-only at the SQL level), webhooks (HMAC-signed + retries + verifier helper), quotas, feature flags, branding, SSO/OIDC, real-time WebSockets (socket.io, tenant-isolated), metrics, impersonation, and multi-provider billing (Stripe / Paddle / Lemon Squeezy: idempotent webhook + dunning + metered + checkout/portal + lifecycle). All optional. |
 
 Two questions to ask before adopting:
 
@@ -100,8 +100,8 @@ every feature end-to-end:
 
 ```bash
 cd examples/api
-npm install
-docker compose -f compose.test.yml up -d
+npm install --legacy-peer-deps
+docker compose up -d
 npm run test:e2e
 ```
 
@@ -126,7 +126,7 @@ state machine.
 npm install --legacy-peer-deps
 npm run typecheck
 npm test
-docker compose -f compose.test.yml up -d
+docker compose -f examples/api/docker-compose.yml up -d
 npm run test:integration
 npm run docs:dev      # live preview of the docs site
 ```

README.md

@@ -53,6 +53,123 @@ multitenancyAdminRoutes({
 - **Optional SSO peer.** The SSO endpoints require `@adonisjs-lasagna/sso`; when it
   is not installed they return 501 and the rest of the admin API keeps working.
 
+## Audit & accountability
+
+Every mutating admin action is recorded automatically in the append-only audit
+log the moment it succeeds. The acting admin comes from your `resolveAdminActor`
+hook (never the request body), the row lands in `backoffice.tenant_audit_logs`,
+and a secret is never written to the metadata. Auditing is best-effort by design:
+a missing resolver or an unreachable audit table degrades to a swallowed no-op
+rather than failing the operation it records.
+
+Actions follow one convention, `admin:<resource>:<verb>`, shared across REST and
+the equivalent ace commands. The caller is distinguished by `actorType`
+(`admin` when an operator id resolves, `system` for an unattributed privileged
+context), not by the action name.
+
+| Action | Fires on | Metadata (ids and flags only) |
+|---|---|---|
+| `admin:tenant:create` | tenant created (`POST /tenants`, `tenant:create`) | `name`, `status` |
+| `admin:tenant:activate` | tenant activated | `status` |
+| `admin:tenant:suspend` | tenant suspended | `status` |
+| `admin:tenant:destroy` | tenant soft-deleted / torn down | `status`, `schemaDropped` |
+| `admin:tenant:restore` | soft-deleted tenant restored | `status` |
+| `admin:tenant:maintenance_enter` / `_exit` | maintenance toggled | `hasMessage` (on enter) |
+| `admin:webhook:create` / `update` / `delete` / `retry` | webhook changes and re-sends | `webhookId` (+ `url`, `events`, `secretGenerated`, `changed`, `deliveryId`) |
+| `admin:feature_flag:create` / `update` / `delete` | flag changes | `flag`, `enabled`, `hasExpiry` |
+| `admin:branding:update` | branding upsert | `changed` (the keys supplied) |
+| `admin:sso:update` / `disable` | SSO config changes | `provider`, `clientId`, `issuerUrl`, `enabled` (never the `clientSecret`) |
+| `admin:quota:set_usage` / `reset` | quota usage written or cleared | `quota`, `value` |
+| `admin:action:dispatch` | a host-registered custom action runs | `name` (never the body or result) |
+| `admin:impersonate:start` / `first-use` / `stop` | impersonation lifecycle | session id, target user, duration, reason |
+
+Idempotent no-ops do not write a row: an already-suspended tenant, a webhook
+`PUT` with an empty body, or disabling an already-disabled SSO config all
+short-circuit with `unchanged: true` and audit nothing. A delete of a missing
+webhook or feature flag returns 404 and records nothing, so the trail never
+contains a deletion that did not happen.
+
+A serialized row looks like this:
+
+```json
+{
+  "actorType": "admin",
+  "actorId": "user-42",
+  "action": "admin:tenant:suspend",
+  "tenantId": "1f1b…",
+  "metadata": { "status": "suspended" },
+  "ipAddress": "203.0.113.10",
+  "createdAt": "2026-06-26T12:00:00.000Z"
+}
+```
+
+Rows are immutable at the database level: three PostgreSQL triggers reject
+`UPDATE`, `DELETE`, and `TRUNCATE`. Read them over HTTP at
+`GET {prefix}/tenants/:id/audit-logs?from=…&to=…` (paginated, date-range
+filterable) or export the full trail with `node ace tenant:audit:export`.
+
+## Configuring the admin actor resolver
+
+`resolveAdminActor` extracts the acting admin id from the authenticated context.
+It powers both impersonation and the audit attribution above.
+
+```ts
+// start/routes.ts
+import { multitenancyAdminRoutes } from '@adonisjs-lasagna/admin'
+import { middleware } from '#start/kernel'
+
+multitenancyAdminRoutes({
+  middleware: middleware.adminAuth(),
+  resolveAdminActor: ({ auth }) => auth.user?.id ?? null,
+})
+```
+
+<Callout type="warning" title="The resolver records who, not what's allowed">
+<code>resolveAdminActor</code> must sit <strong>behind</strong> your
+authorization checks. It records <em>who</em> acted, not <em>which permission</em>
+allowed it. Per-action permission gating (RBAC) belongs in your middleware or
+policies, not in the package. Never read the admin id from the request body.
+</Callout>
+
+The same operation run from the terminal is attributed too: the lifecycle ace
+commands (`tenant:create`, `tenant:activate`, `tenant:suspend`, `tenant:destroy`,
+`tenant:maintenance`) accept `--admin=<id>` to attribute the row to an operator.
+Without it the action is recorded as `system`.
+
+## Retention & monitoring
+
+Admin actions land in `backoffice.tenant_audit_logs`, and retention is your
+responsibility: the package only writes append-only rows, it never prunes them.
+The two supported patterns (ship to a long-term store then purge under a
+privileged role, or partition by month and detach old partitions) are covered in
+the [Audit logs guide](/guides/satellites/audit). For monitoring, register an
+`AuditLogDestinationRegistry` destination to fan rows out to a SIEM, and alert on
+high-signal actions. For example, surface every `admin:tenant:destroy` without a
+matching change ticket:
+
+```bash
+node ace tenant:audit:export --format=json \
+  | jq 'select(.action == "admin:tenant:destroy")'
+```
+
+## Auditing denied attempts
+
+A caller rejected by your auth middleware (401/403) never reaches the package, so
+the admin API cannot record a denial it never sees. That is the correct boundary.
+To audit denied attempts, write the row in your own auth middleware:
+
+```ts
+import { AuditLogService } from '@adonisjs-lasagna/saas-tenancy/services'
+
+const audit = await app.container.make(AuditLogService)
+await audit.log({
+  actorType: 'admin',
+  action: 'admin:access:denied',
+  metadata: { reason: 'missing_scope' },
+  ipAddress: ctx.request.ip(),
+})
+```
+
 ## Extensibility: custom actions
 
 Register an `AdminAction` on the module-level `adminActionRegistry` to add a
@@ -67,6 +184,7 @@ Versioned via `ADMIN_CONTRACT_VERSION`; see the
 ## Read next
 
 - [Admin REST API](/guides/satellites/admin-rest-api); the full endpoint and OpenAPI reference.
+- [Audit logs](/guides/satellites/audit); the append-only trail, retention, and export.
 - [Security](/guides/security); auth, fail-closed mounting, and the actor resolver.
 - [Impersonation](/guides/satellites/impersonation); the impersonation model.
 - [Production checklist](/reference/production-checklist); the hardening runbook before you ship.

docs/guides/satellites/admin.md

@@ -15,11 +15,17 @@ call.
 
 - Impersonation sessions: `admin:impersonate:start`,
   `admin:impersonate:first-use`, and `admin:impersonate:stop`.
-
-That is the only built-in writer today. Everything else (tenant
-lifecycle transitions, webhook changes, branding/SSO updates, quota
-breaches) is recorded by *your* code via `audit.log()`; the
-[lifecycle hooks](/reference/hooks) and [events](/reference/events) give you
+- Admin mutations, when you mount [`@adonisjs-lasagna/admin`](/guides/satellites/admin)
+  or run the lifecycle ace commands (`tenant:create`, `tenant:suspend`,
+  `tenant:destroy`, and the rest): every tenant lifecycle transition, webhook
+  change, feature-flag/branding/SSO update, quota write, and custom-action
+  dispatch records an attributed `admin:<resource>:<verb>` row. See the
+  [Admin guide's Audit & accountability section](/guides/satellites/admin#audit-accountability)
+  for the full action table.
+
+Beyond those, anything specific to *your* application (domain events, quota
+breaches, your own background jobs) is recorded by your code via `audit.log()`;
+the [lifecycle hooks](/reference/hooks) and [events](/reference/events) give you
 clean attachment points:
 
 ```ts

docs/guides/satellites/audit.md

@@ -51,7 +51,7 @@ tenant:backup        --tenant=<id>                 Dump one tenant's schema
 tenant:backups:run                                 Back up every active tenant
 tenant:backup:list   --tenant=<id>                 List a tenant's backups
 tenant:restore       --tenant=<id> --file=<name>   Restore a dump into a tenant
-tenant:clone         --source=<id> --dest=<id>     Clone one tenant's schema into another
+tenant:clone         --source=<id> --name=<n> --email=<e>  Clone a source tenant into a new one
 tenant:import        --tenant=<id> --file=<f.sql>  Import a .sql dump into a tenant schema
 ```
 

docs/guides/satellites/backup.md

@@ -95,6 +95,13 @@ Expiry needs no audit row of its own; the session simply disappears
 when its Redis TTL lapses; the `start` row carries the planned
 duration.
 
+Impersonation is one writer among several. When you mount the
+[admin satellite](/guides/satellites/admin), every other admin mutation
+(tenant lifecycle, webhooks, feature flags, branding, SSO, quotas, custom
+actions) is also recorded under an `admin:<resource>:<verb>` action with the
+acting admin attributed. See the
+[Admin guide's Audit & accountability section](/guides/satellites/admin#audit-accountability).
+
 ## Security guarantees
 
 - Tokens are HMAC-SHA256 over a random 16-byte session id, so a

docs/guides/satellites/impersonation.md

@@ -62,7 +62,8 @@ document is cached for one hour and hardened before it is trusted:
 ## Storing config
 
 Per-tenant OIDC settings live in the `tenant_sso_configs` row (the
-migration stub ships with the core):
+migration stub ships with this package and is published by
+`node ace configure @adonisjs-lasagna/sso`):
 
 ```ts
 import { TenantSsoConfig } from '@adonisjs-lasagna/sso'