docs(plugin-audit): restore the published README's services.audit pointer, in a form published readers can follow (#9589) (#9636)

PR #9531 dropped this README's "See Also" pointer to the runtime-services audit
page because the page documented the settings sink (`record()` / `'set' | 'reset'`)
as if it were the `audit` slot. PR #9587 rewrote the page around the real slot, so
the omission's reason has stopped holding.

Restored because the page carries three things this README deliberately does not:
the slot's own failure posture (`recordAuthEvent` never throws; error once per
process then debug; row lost, nothing retries; silent no-op with no engine or no
`userId`), the event's field-by-field shape, and the settings-sink disambiguation
with its `TypeError` consequence. The README's own slot section states the
interface and the closed action union and stops there.

The restored line is not the removed line. That one was labelled "Audit Logging
Best Practices" — a guide the page has never been — and spelled
`/content/docs/.../audit-service.mdx`, which resolves for neither audience a
published README has: on npm and GitHub a root-relative href resolves against
npmjs.com / github.com, not the docs site. The replacement uses the absolute
`https://docs.objectstack.ai/docs/...` form that create-objectstack's published
READMEs already use.

The one pre-existing site-root-relative docs link in the same file is converted to
the same absolute form; its page and heading anchor both exist, only the spelling
was unfollowable off the docs site.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-steve

.changeset/plugin-audit-readme-audit-service-link.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/plugin-audit": patch
+---
+
+Published README points at the `services.audit` reference again, in the form a published reader can follow (#9589)
+
+PR #9531 dropped this README's "See Also" pointer to the runtime-services audit
+page because the page was measured wrong — it documented `record()` /
+`'set' | 'reset'` (the settings sink) as if that were the `audit` slot. PR #9587
+rewrote the page around the real slot, so the reason for the omission has stopped
+holding, and the link is restored.
+
+It is restored because the page carries three things this README deliberately
+does not, each verified against the page as it stands on `main` rather than
+against the PR title that rewrote it:
+
+- **the failure posture of the slot itself** — `recordAuthEvent` never throws; a
+  failed ledger insert is reported at `error` level once per process and then
+  drops to `debug`, the row is lost and nothing retries it, and the call silently
+  no-ops when no data engine resolves or when `userId` is absent. This README
+  documents the *record-view batcher's* two failure postures, which are a
+  different code path; it says nothing about this one.
+- **the event's field-by-field shape** — that `userId` must be a real `sys_user`
+  id, that `sessionId` lands on `record_id` with `object_name` fixed to
+  `sys_session`, that `organizationId` stamps the tenant columns and an unstamped
+  row is one non-administrator members can never see, and that `context` is
+  serialized into `metadata`. This README states the slot's interface and its
+  closed `'login' | 'logout'` action union, and deliberately stops there.
+- **the settings-sink disambiguation** — that `SettingsAuditSink.record()` is
+  never registered as or resolved from this slot, and that
+  `getService('audit').record({ ... })` therefore fails with a `TypeError`.
+
+The restored line is **not** the line #9531 removed. That one read
+`[Audit Logging Best Practices](/content/docs/kernel/runtime-services/audit-service.mdx)`
+— a label describing a best-practices guide the page has never been, and a
+repo-path-rooted URL that resolves for neither of this README's published
+audiences. A README in the package's `files` array is rendered on npm and on
+GitHub, where a root-relative href resolves against `npmjs.com` / `github.com`,
+not against the docs site. The replacement uses the absolute
+`https://docs.objectstack.ai/docs/...` form that `create-objectstack`'s published
+READMEs already use, and its annotation states what the page adds — so the next
+author weighing the same omission can check the justification instead of
+reconstructing it.
+
+The one pre-existing site-root-relative docs link in this same file
+(`/docs/permissions/permission-sets#access-depth...`, added by the same PR) is
+converted to the same absolute form. Its target page and heading anchor both
+exist; only the spelling was unfollowable off the docs site.

packages/plugins/plugin-audit/README.md

@@ -340,7 +340,7 @@ Permission sets that use the **hierarchy-relative depth scopes** (`own_and_repor
 `@objectstack/security-enterprise`. The open edition ships no resolver, so those scopes
 **fail closed to `own`** — they never widen visibility without it. A grant written to let
 managers read their reports' audit rows will, on an open build, show them only their own.
-See [Access depth](/docs/permissions/permission-sets#access-depth--readscope--writescope-adr-0057-d1).
+See [Access depth](https://docs.objectstack.ai/docs/permissions/permission-sets#access-depth--readscope--writescope-adr-0057-d1).
 
 `sys_comment`'s record-level edit gates resolve the `sharing` service lazily; without it
 those checks degrade to parent-record read visibility. If the engine exposes no middleware
@@ -394,3 +394,6 @@ Apache-2.0. See [LICENSING.md](../../../LICENSING.md).
 
 - [@objectstack/plugin-security](../plugin-security/) — permissions, RLS and field-level security
 - [@objectstack/plugin-auth](../plugin-auth/) — the caller of the `audit` slot's auth-event ingress
+- [`services.audit` reference](https://docs.objectstack.ai/docs/kernel/runtime-services/audit-service) — the slot's
+  full event shape, its never-throws failure posture, and why `SettingsAuditSink.record()`
+  is not this slot