From 990269db3a14dd167ffb8bfce368adafa75f60fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?N=C3=A9stor?= <nestor@nstlopez.com>
Date: Thu, 9 Apr 2026 18:16:53 +0200
Subject: [PATCH 1/2] docs: add beta feedback callout to readme

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 35eca9f..46a048c 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,9 @@ Astro bridge package in this repo: `@module-federation/astro`.
 Published package source: `packages/astro`.
 Example apps: `apps/example` (see `apps/example/README.md`).
 
+> [!IMPORTANT]
+> `@module-federation/astro` is still in beta. Expect rough edges and API changes while the integration settles. Feedback, bugs, and edge cases are welcome in GitHub Issues for this repo.
+
 ## Package usage
 
 ```ts

From ba5935c691f28d3b9d3fbc70a0e1f66060df53f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?N=C3=A9stor?= <nestor@nstlopez.com>
Date: Thu, 9 Apr 2026 18:17:44 +0200
Subject: [PATCH 2/2] docs: make readme package-first

---
 README.md | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 46a048c..85a6a8c 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,16 @@
 # Astro Module Federation
 
-Repo: `module-federation/astro`
-
-Workspace orchestration: Turborepo (`turbo` + `turbo.json`).
-Plugin build: `tsdown` (`packages/astro/tsdown.config.ts`).
-
-Module Federation plugin: `@module-federation/vite`.
-Astro bridge package in this repo: `@module-federation/astro`.
-Published package source: `packages/astro`.
-Example apps: `apps/example` (see `apps/example/README.md`).
+Use Module Federation in Astro apps with `@module-federation/astro`, built on top of `@module-federation/vite`.
 
 > [!IMPORTANT]
 > `@module-federation/astro` is still in beta. Expect rough edges and API changes while the integration settles. Feedback, bugs, and edge cases are welcome in GitHub Issues for this repo.
 
+## What you get
+
+- Astro integration wrapper around Module Federation for host/remote setups.
+- Dev/runtime wiring so `.astro` script imports and SSR remote imports work.
+- Support for remote Astro components, server functions, and browser-side widgets.
+
 ## Package usage
 
 ```ts
@@ -31,6 +29,13 @@ export default defineConfig({
 });
 ```
 
+## Example apps
+
+- Host app: `apps/example/host` on `http://localhost:4321`
+- Remote app: `apps/example/remote` on `http://localhost:4322`
+- Start both from repo root with `pnpm dev`
+- More example details: `apps/example/README.md`
+
 ## Behavior
 
 - Remote strings are normalized to explicit MF remote objects.
@@ -60,3 +65,10 @@ pnpm --filter @module-federation/astro test
 - `mf-vite` already emits `ssrRemoteEntry` in its manifest, and MF runtime prefers that entry on the server.
 - Rsbuild/Rslib providers should emit SSR assets with `target: 'dual'` (or legacy `ssr: true`).
 - Astro as consumer keeps using MF runtime on the server; the loaded module can then be rendered as `<Component />` if it exports a server-renderable component.
+
+## Repo layout
+
+- Package: `packages/astro`
+- Example apps: `apps/example`
+- Main package README: `packages/astro/README.md`
+- Release docs: `docs/RELEASING.md`