docs: umbrella accuracy pass (self-updating versions + @rudderjs framing)

Architecture.md

@@ -44,7 +44,7 @@ Realized fully, GemStack is the unified home for agnostic engines: `@gemstack/ai
 
 These are not orphaned code needing a home: `@universal-orm` is already its own deliberate npm scope, and `universal-schema` sits under `@vike-data`. So there are **three agnostic-ish scopes in play** (`@gemstack`, `@universal-orm`, `@vike-data`). The decision is therefore not "where should this code live" but **"do we consolidate the agnostic engines under one umbrella (`@gemstack`), or keep `@universal-orm` as a parallel brand?"** Since `@universal-orm` is co-developed, this is a decide-with-the-Vike-team call, gated on brand traction.
 
-When a candidate does graduate, follow the `@gemstack/ai-sdk` playbook exactly: copy the source in, rename to the `@gemstack/*` name, leave a deprecated re-export shim at the old name, reset to a fresh `0.x` line, then repoint dependents.
+When a candidate does graduate, follow the `@gemstack/ai-sdk` playbook exactly: copy the source in, rename to the `@gemstack/*` name, leave a re-export at the old name, reset to a fresh `0.x` line, then repoint dependents. The old-name package takes one of two shapes: a **deprecated shim** (pure re-export, slated for eventual removal) or — when it has framework-coupled pieces that cannot graduate (provider wiring, ORM-backed stores, CLI) — a **living framework binding** that re-exports the agnostic core and owns those bindings. `@rudderjs/ai` is the latter: it re-exports `@gemstack/ai-sdk` and keeps the Rudder `AiProvider`, ORM stores, and `make:agent` / `ai:eval` CLI. Don't mislabel a binding as deprecated.
 
 ## The AI family
 

README.md

@@ -8,11 +8,11 @@ GemStack is shared, community-governed infrastructure built with the [Vike](http
 
 | Package | Description | Version |
 |---|---|---|
-| [`@gemstack/ai-sdk`](./packages/ai-sdk) | The agent runtime: providers, the agent loop, tools, streaming, middleware, structured output, memory, and evals. The engine the rest of the AI family builds on. | `0.3.0` |
-| [`@gemstack/ai-skills`](./packages/ai-skills) | Portable capability bundles: load `SKILL.md` skills (instructions + tools + resources) and compose them onto an agent on demand. | `0.1.0` |
-| [`@gemstack/ai-autopilot`](./packages/ai-autopilot) | Orchestration: a Supervisor that plans, dispatches subagents (bounded concurrency + budget guardrails), and synthesizes the result. | `0.1.0` |
-| [`@gemstack/ai-mcp`](./packages/ai-mcp) | The agent/MCP bridge: consume a remote MCP server's tools as agent tools, and expose an agent as an MCP server. | `0.1.0` |
-| [`@gemstack/mcp`](./packages/mcp) | A standalone framework for *authoring* MCP servers: tools, resources, prompts, decorators, OAuth 2.1, a framework-neutral HTTP handler, and a test client. Agent-agnostic. | `0.2.0` |
+| [`@gemstack/ai-sdk`](./packages/ai-sdk) | The agent runtime: providers, the agent loop, tools, streaming, middleware, structured output, memory, and evals. The engine the rest of the AI family builds on. | [![npm](https://img.shields.io/npm/v/@gemstack/ai-sdk)](https://www.npmjs.com/package/@gemstack/ai-sdk) |
+| [`@gemstack/ai-skills`](./packages/ai-skills) | Portable capability bundles: load `SKILL.md` skills (instructions + tools + resources) and compose them onto an agent on demand. | [![npm](https://img.shields.io/npm/v/@gemstack/ai-skills)](https://www.npmjs.com/package/@gemstack/ai-skills) |
+| [`@gemstack/ai-autopilot`](./packages/ai-autopilot) | Orchestration: a Supervisor that plans, dispatches subagents (bounded concurrency + budget guardrails), and synthesizes the result. | [![npm](https://img.shields.io/npm/v/@gemstack/ai-autopilot)](https://www.npmjs.com/package/@gemstack/ai-autopilot) |
+| [`@gemstack/ai-mcp`](./packages/ai-mcp) | The agent/MCP bridge: consume a remote MCP server's tools as agent tools, and expose an agent as an MCP server. | [![npm](https://img.shields.io/npm/v/@gemstack/ai-mcp)](https://www.npmjs.com/package/@gemstack/ai-mcp) |
+| [`@gemstack/mcp`](./packages/mcp) | A standalone framework for *authoring* MCP servers: tools, resources, prompts, decorators, OAuth 2.1, a framework-neutral HTTP handler, and a test client. Agent-agnostic. | [![npm](https://img.shields.io/npm/v/@gemstack/mcp)](https://www.npmjs.com/package/@gemstack/mcp) |
 
 ### How they fit together
 
@@ -51,7 +51,7 @@ This is a pnpm + Turborepo + Changesets monorepo. Runnable examples live under [
 
 ## Origin
 
-The AI family was spun out of Rudder's mature `@rudderjs/ai` (v1.17.x) and re-versioned under the GemStack umbrella; `@gemstack/mcp` is the graduation of `@rudderjs/mcp`. The old `@rudderjs/*` names continue as thin deprecated re-exports.
+The AI family was spun out of Rudder's mature `@rudderjs/ai` (v1.17.x) and re-versioned under the GemStack umbrella; `@gemstack/mcp` is the graduation of `@rudderjs/mcp`. The old `@rudderjs/*` names live on as the **Rudder bindings** over these engines: they re-export the agnostic core and add the framework-specific pieces that cannot graduate (e.g. `@rudderjs/ai`'s `AiProvider`, ORM-backed stores, doctor check, and `make:agent` / `ai:eval` CLI).
 
 ## Governance
 

packages/ai-sdk/README.md

@@ -2,7 +2,7 @@
 
 AI engine: providers, agents, tools, streaming, middleware, structured output, conversation memory, evals, computer-use, and testing fakes.
 
-The first [GemStack](https://github.com/gemstack-land/gemstack) package. Spun out of Rudder's `@rudderjs/ai` (carried forward from the 1.17.x line, renamed and re-versioned under the GemStack umbrella). The Rudder package now ships as a thin deprecated re-export of this one.
+The first [GemStack](https://github.com/gemstack-land/gemstack) package. Spun out of Rudder's `@rudderjs/ai` (carried forward from the 1.17.x line, renamed and re-versioned under the GemStack umbrella). The Rudder package, `@rudderjs/ai`, now re-exports this engine and adds the Rudder-specific bindings on top (the `AiProvider`, ORM-backed stores, doctor check, and `make:agent` / `ai:eval` CLI) — it is the Rudder binding over this engine, not a dying shim.
 
 ## Installation