diff --git a/.changeset/plugin-calendar-readme-export-surface-5010.md b/.changeset/plugin-calendar-readme-export-surface-5010.md
new file mode 100644
index 0000000000..bb32217c23
--- /dev/null
+++ b/.changeset/plugin-calendar-readme-export-surface-5010.md
@@ -0,0 +1,44 @@
+---
+'@object-ui/plugin-calendar': patch
+---
+
+`plugin-calendar`'s README no longer documents imports the package does not export.
+
+Three defects in `packages/plugin-calendar/README.md`, all of which made a
+copy-pasted snippet fail to compile. Checked by taking the package's real export
+name set off `src/index.tsx` through the TypeScript compiler API and cross-checking
+every import statement in the README against it — including multi-line import
+blocks, which a single-line grep cannot see.
+
+1. **Fabricated (deleted).** A "Manual Registration" section taught
+   `import { calendarComponents } from '@object-ui/plugin-calendar'` followed by
+   `Object.entries(calendarComponents).forEach(register)`. There is no
+   `calendarComponents` export and never was — the identifier does not occur
+   anywhere in `src/`. Copying it gave `undefined`, and `Object.entries(undefined)`
+   throws a `TypeError`, so the section could not run at all. Registration in this
+   package is purely a side effect of importing the entry point, so there is no
+   components map to iterate. The fabricated section is replaced by what the
+   side-effect import actually claims (the three registered schema types and their
+   namespaced keys) and by the package's real export surface — `ObjectCalendar`,
+   `CalendarView`, `ObjectCalendarRenderer` plus the component prop types. Hosts
+   that want their own registry key are shown the honest way to get one:
+   registering the exported `ObjectCalendarRenderer` under it.
+
+2. **Wrong import path (path corrected).** `CalendarViewSchema` was imported from
+   `@object-ui/plugin-calendar`. The type is real but belongs to `@object-ui/types`;
+   this package imports it and does not re-export it, so the documented import was
+   a "no exported member" error. The path now points at `@object-ui/types`.
+
+3. **Name collision (import re-pointed).** Correcting (2) alone still left the
+   snippet uncompilable: the same example imported `CalendarEvent` from
+   `@object-ui/plugin-calendar`, which is a real export but a *different* type —
+   the `CalendarView` component's runtime shape (`id: string | number`,
+   `start: Date`), not the authored JSON shape (`id: string`, `start: string | Date`)
+   that `CalendarViewSchema.events` requires and that the README's own "Calendar
+   Event Structure" section documents. The example's ISO-string values therefore did
+   not typecheck, and the plugin's event type was not assignable to the schema's.
+   Both authored types now come from `@object-ui/types`, and the two same-named
+   types are documented side by side so the next reader does not re-pick the wrong one.
+
+No exports were added to make the README true — the docs were moved to the code,
+not the reverse.
diff --git a/packages/plugin-calendar/README.md b/packages/plugin-calendar/README.md
index 8577145028..f41fe647a6 100644
--- a/packages/plugin-calendar/README.md
+++ b/packages/plugin-calendar/README.md
@@ -100,16 +100,48 @@ const schema = {
 };
 ```
 
-### Manual Registration
+### What the side-effect import registers
+
+Registration is *only* a side effect of importing the package — the single
+`import '@object-ui/plugin-calendar'` above is the whole of it. There is no
+components map to iterate over: importing the entry point runs the
+`ComponentRegistry.register(...)` calls in `src/index.tsx` and
+`src/calendar-view-renderer.tsx`, which claim these schema types:
+
+| Schema `type` | Namespaced key | Renderer |
+| --- | --- | --- |
+| `object-calendar` | `plugin-calendar:object-calendar` | `ObjectCalendarRenderer` |
+| `calendar` | `view:calendar` | `ObjectCalendarRenderer` |
+| `calendar-view` | `plugin-calendar:calendar-view` | internal wrapper around `CalendarView` (not exported) |
+
+Both spellings work — the namespaced key and the bare `type` fallback.
+
+### Public exports
+
+The package exports components and their types, not a registry map:
+
+```typescript
+import {
+  ObjectCalendar, // ObjectQL-integrated calendar component
+  CalendarView, // standalone calendar component
+  ObjectCalendarRenderer, // the registered renderer for `object-calendar` / `calendar`
+} from '@object-ui/plugin-calendar';
+
+import type {
+  ObjectCalendarComponentProps,
+  CalendarViewProps,
+  CalendarEvent,
+} from '@object-ui/plugin-calendar';
+```
+
+To serve the calendar under a registry key of your own, register the exported
+renderer under that key:
 
 ```typescript
-import { calendarComponents } from '@object-ui/plugin-calendar';
 import { ComponentRegistry } from '@object-ui/core';
+import { ObjectCalendarRenderer } from '@object-ui/plugin-calendar';
 
-// Register calendar components
-Object.entries(calendarComponents).forEach(([type, component]) => {
-  ComponentRegistry.register(type, component);
-});
+ComponentRegistry.register('my-calendar', ObjectCalendarRenderer);
 ```
 
 ## Schema API
@@ -131,6 +163,8 @@ Display a monthly calendar with events:
 
 ### Calendar Event Structure
 
+The authored event shape, declared by `@object-ui/types`:
+
 ```typescript
 interface CalendarEvent {
   id: string;
@@ -238,8 +272,11 @@ const schema = {
 
 ## TypeScript Support
 
+The **authored** (JSON metadata) types live in `@object-ui/types`, not in this
+package — this package imports them too, and does not re-export them:
+
 ```typescript
-import type { CalendarViewSchema, CalendarEvent } from '@object-ui/plugin-calendar';
+import type { CalendarViewSchema, CalendarEvent } from '@object-ui/types';
 
 const event: CalendarEvent = {
   id: '1',
@@ -254,6 +291,16 @@ const schema: CalendarViewSchema = {
 };
 ```
 
+> **Two different `CalendarEvent` types, same name.** The one above, from
+> `@object-ui/types`, is the *authored* event: `id: string` and
+> `start` / `end` accept ISO strings — that is the shape documented under
+> [Calendar Event Structure](#calendar-event-structure) and the one a
+> `calendar-view` schema carries. This package also exports a `CalendarEvent`
+> (`CalendarViewProps['events']`), which is the `CalendarView` **component's
+> runtime** type: `id: string | number` and `start: Date` / `end?: Date`. Use
+> the `@object-ui/types` one for metadata and the plugin one when you render
+> `CalendarView` yourself in React; they are not interchangeable.
+
 ## Links
 
 - 📚 [Documentation](https://www.objectui.org/docs/plugins/plugin-calendar)