fix(devx): assert that a published README's repo-relative targets exist (#10813) (#10892)

`check:published-readme-links` read the docs-site URLs a published README
carries and said nothing about its repo-relative paths. `packages/runtime/README.md`
linked six targets that are not in the tree, and a census across the whole
published population found nine, in four packages. Nothing read them: the
assertions above this one read ABSOLUTE urls, `check:published-readme-exports`
reads fenced import lines, and the lychee lane never sees `packages/**/README.md`.

Adds assertion 5 — a repo-relative destination must name something in the
tree — to the existing gate rather than a second script, so it reuses that
gate's population, extractor and classifier bucket. The gate's own header had
already named this omission ("a different claim, owned by nothing here yet").

Deliberately only the decidable half. Whether a relative href means anything to
a reader on npmjs.com is a separate question: npm renders the README outside the
repo, so EVERY relative link is unresolvable there, including the 101 that are
correct in-tree. Failing them all would be a ruling on link rewriting, not a
scan, and this repo's published READMEs lean on the relative form throughout.
Assertion 5 says GITHUB in its message for that reason.

Vacuity is refused at the population level, never the document level: 18 of the
60 published documents carry no relative link at all, so per-document silence
proves nothing. `run()` throws when the whole scan classifies nothing relative,
the same way it already throws on zero links, and the green line prints the
resolved count so a classifier that stopped recognising the bucket shows up as
a number that fell.

The six runtime targets were each traced to where the content went rather than
deleted: the three MINI_KERNEL_*.md docs were removed from the repo root in
January (d709ecc, 5051 deletions, nothing added) and the kernel reference is
the docs site now; `examples/host/` became app-host, then apps/server, then
apps/objectos, then moved to objectstack-ai/cloud; `examples/msw-react-crud/`
became app-react-crud, then apps/console, and ships as `@object-ui/console`;
`test-mini-kernel.ts` was a root scratch script whose successor is this
package's own 179-file suite under `src/` — which is what the truncated bullet
with the unterminated backtick was reaching for.

The other three packages: `../../plugins/driver-sql` is stale since the driver
moved to `packages/drivers/` (#5618); `plugin-org-scoping`, `service-tenant`
and `service-marketplace` are in no directory of this repo, so those links are
dropped and the names kept as code spans — the spelling those same files
already use for a package they cannot point at in-tree.


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

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

Author: os-zhuang

.changeset/published-readme-relative-target-existence.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/hono": patch
+"@objectstack/plugin-security": patch
+"@objectstack/service-package": patch
+---
+
+docs: repair the dead repo-relative targets in four published READMEs (#10813)
+
+A published README ships inside the npm tarball, so a dead relative link in one
+is shipped to every reader who installs the package. Nine of them were measured
+across four packages, and nothing read them: `check:published-readme-links`
+checked docs-site URLs, `check:published-readme-exports` checked fenced import
+lines, and the lychee lane never sees `packages/**/README.md`.
+
+`@objectstack/runtime` carried six dead targets. Each was traced to where the
+content actually went rather than deleted:
+
+- `MINI_KERNEL_GUIDE.md`, `MINI_KERNEL_ARCHITECTURE.md` and
+  `MINI_KERNEL_IMPLEMENTATION.md` were deleted from the repo root in January as
+  "redundant markdown files" (d709ecce68 — 14 files, 5051 deletions, nothing
+  added). The kernel reference they described is the docs site now, so the
+  Documentation section is the same footer eight sibling READMEs already use.
+- `examples/host/` was renamed to `examples/app-host`, then `apps/server`, then
+  `apps/objectos`, and finally split out to `objectstack-ai/cloud`. In-repo, an
+  HTTP server in front of the runtime is `@objectstack/plugin-hono-server` plus
+  the `@objectstack/hono` adapter, so the bullet points there.
+- `examples/msw-react-crud/` became `examples/app-react-crud`, then
+  `apps/console`, and now ships as `@object-ui/console` from another repo.
+- `test-mini-kernel.ts` was a root-level scratch script; this package's suite is
+  179 test files under `src/`.
+- The section also ended on a truncated bullet with an unterminated backtick
+  (`` - `packages/runtime/src/ ``), which is now a real pointer to that suite.
+
+The other three packages: `@objectstack/hono` and `@objectstack/service-package`
+still spelled `@objectstack/driver-sql` as `../../plugins/driver-sql`, stale
+since the driver moved to `packages/drivers/` (#5618). `@objectstack/plugin-security`
+and `@objectstack/service-package` linked three packages that are in no directory
+of this repo (`plugin-org-scoping`, `service-tenant`, `service-marketplace`);
+those links are dropped and the names kept as code spans, which is the spelling
+those same files already use for a package they cannot point at in-tree. Whether
+those three packages exist at all is a separate question, filed separately.

packages/adapters/hono/README.md

@@ -66,7 +66,7 @@ app.use('/api/*', objectStackMiddleware(kernel));
 ## Edge runtime notes
 
 - Hono adapter is the **preferred** adapter for Cloudflare Workers, Deno Deploy, Bun, and Vercel Edge.
-- Drivers differ by runtime: use [`@objectstack/driver-sql`](../../plugins/driver-sql) on Node. (Edge/multi-tenant turso driver ships in ObjectStack Cloud.)
+- Drivers differ by runtime: use [`@objectstack/driver-sql`](../../drivers/driver-sql) on Node. (Edge/multi-tenant turso driver ships in ObjectStack Cloud.)
 - Persist no long-lived state in module scope beyond the `kernel` instance.
 
 ## When to use

packages/plugins/plugin-security/README.md

@@ -37,7 +37,7 @@ await kernel.bootstrap();
 
 `SecurityPlugin` is single-tenant by default. It enforces RBAC, owner-based RLS, and Field-Level Security regardless of mode.
 
-For **multi-tenant** (logical row-level Organization scoping) install [`@objectstack/plugin-org-scoping`](../plugin-org-scoping/README.md) *before* SecurityPlugin:
+For **multi-tenant** (logical row-level Organization scoping) install `@objectstack/plugin-org-scoping` *before* SecurityPlugin:
 
 ```typescript
 import { OrgScopingPlugin } from '@objectstack/plugin-org-scoping';
@@ -92,7 +92,7 @@ Compilation output is a filter AST merged into every query's `where` clause, so
 ## When to use
 
 - ✅ Any multi-user deployment.
-- ✅ Enforcing tenant isolation (combine with [`@objectstack/service-tenant`](../../services/service-tenant)).
+- ✅ Enforcing tenant isolation (combine with `@objectstack/service-tenant`).
 
 ## When not to use
 

packages/runtime/README.md

@@ -256,11 +256,18 @@ interface PluginContext {
 
 ## Examples
 
-See the `examples/` directory for complete examples:
-- `examples/host/` - Full server setup with Hono
-- `examples/msw-react-crud/` - Browser-based setup with MSW
-- `test-mini-kernel.ts` - Comprehensive kernel test suite
-- `packages/runtime/src/
+Complete, CI-exercised examples live in the repo's [`examples/`](../../examples)
+catalog. The three that build on this package:
+
+- [`app-todo`](../../examples/app-todo) — the smallest complete app; the fastest read of the `AppPlugin` conventions.
+- [`app-crm`](../../examples/app-crm) — relational modeling driven through the metadata loading pipeline.
+- [`app-showcase`](../../examples/app-showcase) — the kitchen-sink conformance fixture.
+
+To put an HTTP server in front of one, see [`@objectstack/plugin-hono-server`](../plugins/plugin-hono-server)
+(boots the kernel behind Hono) and [`@objectstack/hono`](../adapters/hono) (the adapter itself).
+
+This package's own behaviour is pinned by the test suite under [`src/`](./src) —
+`pnpm --filter @objectstack/runtime test`.
 
 ## Benefits of MiniKernel
 
@@ -640,9 +647,10 @@ Defaults are noop — zero overhead until you plug an adapter.
 
 ## Documentation
 
-- [MiniKernel Guide](../../MINI_KERNEL_GUIDE.md) - Complete API documentation and patterns
-- [MiniKernel Architecture](../../MINI_KERNEL_ARCHITECTURE.md) - Architecture diagrams and flows
-- [MiniKernel Implementation](../../MINI_KERNEL_IMPLEMENTATION.md) - Implementation details
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references/kernel>
+- 🛡️ Hardening: [`docs/HARDENING.md`](../../docs/HARDENING.md)
+- 📈 Observability: [`docs/OBSERVABILITY.md`](../../docs/OBSERVABILITY.md)
 
 ## License
 

packages/services/service-package/README.md

@@ -94,7 +94,7 @@ CREATE INDEX IF NOT EXISTS idx_packages_latest
 
 ## Requirements
 
-- A driver plugin that registers an `IDataEngine` under the service name `'objectql'` with `execute()` support — typically [`@objectstack/driver-sql`](../../plugins/driver-sql). `@objectstack/driver-memory` can be used for tests but does not persist across restarts. (ObjectStack Cloud additionally ships `@objectstack/driver-turso` for edge/multi-tenant.)
+- A driver plugin that registers an `IDataEngine` under the service name `'objectql'` with `execute()` support — typically [`@objectstack/driver-sql`](../../drivers/driver-sql). `@objectstack/driver-memory` can be used for tests but does not persist across restarts. (ObjectStack Cloud additionally ships `@objectstack/driver-turso` for edge/multi-tenant.)
 
 ## When to use
 
@@ -105,13 +105,13 @@ CREATE INDEX IF NOT EXISTS idx_packages_latest
 ## When not to use
 
 - ❌ Not a package manager for npm/TypeScript source packages — use npm.
-- ❌ Not a runtime plugin loader — pair with [`@objectstack/service-marketplace`](../service-marketplace) or a custom loader for that.
+- ❌ Not a runtime plugin loader — pair with `@objectstack/service-marketplace` or a custom loader for that.
 
 ## Related Packages
 
 - [`@objectstack/core`](../../core) — kernel hosting this plugin.
 - [`@objectstack/spec`](../../spec) — provides `ObjectStackManifest` and `IDataEngine` contracts.
-- [`@objectstack/driver-sql`](../../plugins/driver-sql) — supplies the `'objectql'` service. (ObjectStack Cloud also ships `@objectstack/driver-turso`.)
+- [`@objectstack/driver-sql`](../../drivers/driver-sql) — supplies the `'objectql'` service. (ObjectStack Cloud also ships `@objectstack/driver-turso`.)
 
 ## Links