docs(packaging): per-package READMEs + English descriptions (for 1.0.1)

Directory.Build.props

@@ -1,7 +1,8 @@
 <Project>
 
   <!-- Configuración transversal de toda la solución Weft (net10.0 / C# 13).
-       Los .csproj individuales solo añaden Description y referencias. -->
+       Los .csproj individuales añaden Description y referencias; cada librería publicable
+       lleva su propio README.md (empaquetado como PackageReadmeFile, ver abajo). -->
 
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
@@ -34,8 +35,14 @@
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
+  <!-- Each publishable library ships its own README.md (in the project folder), embedded in the .nupkg. -->
+  <ItemGroup Condition="'$(IsTestProject)' != 'true' AND Exists('$(MSBuildProjectDirectory)/README.md')">
+    <None Include="README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
   <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
     <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
   </PropertyGroup>

src/Weft.Core/README.md

@@ -0,0 +1,33 @@
+# Weft.Core
+
+Safe .NET binding to [`yrs`](https://github.com/y-crdt/y-crdt) (the Rust core of Yjs) via an in-house
+C-ABI shim, plus the engine abstractions and the concurrency broker the rest of Weft builds on.
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Core
+```
+
+The native `yrs` shim ships in the package and is resolved per RID (`linux-x64`, `linux-arm64`,
+`win-x64`, `osx-arm64`) automatically — no manual native setup.
+
+## What it provides
+
+- **`ICrdtEngine` / `ICrdtDoc`** — create/load documents, text operations, export
+  state / state-vector / delta, apply updates.
+- **Safe native lifecycle** — `SafeHandle` + an explicit ownership contract; the GC never touches
+  native memory and no panic crosses the C boundary.
+- **Concurrency** (`Weft.Concurrency`) — `DocumentBroker` / `DocumentSession`, one actor per document
+  for safe concurrent access at scale. `ICrdtDoc` itself is not thread-safe.
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+- Per-package API overview: <https://github.com/StrangeDaysTech/weft/blob/main/docs/api/README.md>
+
+Licensed under Apache-2.0.

src/Weft.Core/Weft.Core.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — binding seguro a yrs vía shim C-ABI propio, abstracciones ICrdtEngine/ICrdtDoc y concurrencia serializada por documento.</Description>
+    <Description>Weft — safe .NET binding to yrs via an in-house C-ABI shim: ICrdtEngine/ICrdtDoc abstractions and per-document serialized concurrency.</Description>
     <!-- Exigido por el source generator [LibraryImport] (emite marshalling unsafe). -->
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <!-- Empaqueta el cdylib weft_yrs_ffi por RID bajo runtimes/<rid>/native/ (T055). -->

src/Weft.Loro/README.md

@@ -0,0 +1,34 @@
+# Weft.Loro
+
+A dual-path engine adapter that runs Weft over the [Loro](https://github.com/loro-dev/loro) CRDT
+engine (via the `weft-loro-ffi` shim) behind the same `ICrdtEngine` / `ICrdtDoc` abstractions — the
+living proof that Weft's engine is replaceable (constitution principle P-IV).
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Loro   # brings in Weft.Core
+```
+
+The native Loro shim ships in the package and is resolved per RID automatically.
+
+## What it provides
+
+- **`LoroEngine`** — an `ICrdtEngine` backed by Loro; the entire `Weft.Versioning` layer runs over it
+  unchanged.
+- **Optional `INativeVersioning`** — exposes Loro's native versioning capabilities (shallow snapshot,
+  native diff/branch-merge probes) without making them a dependency of the core.
+
+> Note: the redistributed Loro binary statically links three MPL-2.0 crates (`im`, `bitmaps`,
+> `sized-chunks`). MPL-2.0 is compatible with proprietary use; see the repository's
+> `THIRD-PARTY-NOTICES.md`. The default `yrs` engine (`Weft.Core`) is fully permissive.
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+
+Licensed under Apache-2.0.

src/Weft.Loro/Weft.Loro.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — adaptador dual-path sobre el motor CRDT Loro (vía shim weft-loro-ffi). Prueba la portabilidad de la abstracción ICrdtEngine (constitución P-IV).</Description>
+    <Description>Weft — dual-path adapter over the Loro CRDT engine (via the weft-loro-ffi shim). Exercises the portability of the ICrdtEngine abstraction (constitution P-IV).</Description>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <!-- Empaqueta el cdylib weft_loro_ffi por RID bajo runtimes/<rid>/native/ (T055). -->
     <WeftNativeLib>weft_loro_ffi</WeftNativeLib>

src/Weft.Server.Persistence.EFCore/README.md

@@ -0,0 +1,29 @@
+# Weft.Server.Persistence.EFCore
+
+An `IDocumentStore` adapter for [Weft.Server](https://www.nuget.org/packages/Weft.Server) backed by
+Entity Framework Core: opaque per-document blob persistence (a consolidated snapshot + accumulated
+updates) with transactional compaction.
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Server.Persistence.EFCore
+```
+
+## What it provides
+
+- **`AddWeftEFCoreDocumentStore(...)`** — registers the adapter.
+- **Provider-agnostic** — the consumer configures the EF Core provider (SQLite, PostgreSQL,
+  SQL Server, …) via `DbContextOptions`.
+- Passes the same shared `IDocumentStore` contract suite as the in-memory, filesystem, and Redis
+  adapters, so behavior is interchangeable.
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+
+Licensed under Apache-2.0.

src/Weft.Server.Persistence.EFCore/Weft.Server.Persistence.EFCore.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — adaptador IDocumentStore sobre Entity Framework Core (persistencia de blobs opacos por documento, con snapshot + updates y compaction transaccional). Provider-agnóstico: el consumidor configura el provider (SQLite, PostgreSQL, SQL Server, …) vía DbContextOptions.</Description>
+    <Description>Weft — IDocumentStore adapter over Entity Framework Core (opaque per-document blob persistence: snapshot + updates with transactional compaction). Provider-agnostic: the consumer configures the provider (SQLite, PostgreSQL, SQL Server, …) via DbContextOptions.</Description>
     <RootNamespace>Weft.Server.Persistence.EFCore</RootNamespace>
   </PropertyGroup>
 

src/Weft.Server.Persistence.Redis/README.md

@@ -0,0 +1,28 @@
+# Weft.Server.Persistence.Redis
+
+An `IDocumentStore` adapter for [Weft.Server](https://www.nuget.org/packages/Weft.Server) backed by
+Redis (via StackExchange.Redis): the snapshot as a string + updates as a list, with atomic compaction
+via a transaction.
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Server.Persistence.Redis
+```
+
+## What it provides
+
+- **`AddWeftRedisDocumentStore(...)`** — registers the adapter.
+- Compatible with any Redis-wire server (Redis, Valkey).
+- Passes the same shared `IDocumentStore` contract suite as the in-memory, filesystem, and EF Core
+  adapters, so behavior is interchangeable.
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+
+Licensed under Apache-2.0.

src/Weft.Server.Persistence.Redis/Weft.Server.Persistence.Redis.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — adaptador IDocumentStore sobre Redis (StackExchange.Redis): snapshot como string + updates como lista, con compaction atómica vía transacción. Compatible con servidores wire-Redis (Redis, Valkey).</Description>
+    <Description>Weft — IDocumentStore adapter over Redis (StackExchange.Redis): snapshot as a string + updates as a list, with atomic compaction via a transaction. Compatible with Redis-wire servers (Redis, Valkey).</Description>
     <RootNamespace>Weft.Server.Persistence.Redis</RootNamespace>
   </PropertyGroup>
 

src/Weft.Server/README.md

@@ -0,0 +1,35 @@
+# Weft.Server
+
+A y-sync WebSocket relay for ASP.NET Core: it speaks the standard Yjs `y-sync` protocol, so existing
+editor clients (Tiptap + `y-prosemirror`, `y-websocket`) connect with no adaptation.
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Server
+```
+
+## What it provides
+
+- **DI wiring** — `AddWeftServer(...)` + `MapWeft("/path")` → `path/{docId}`.
+- **`IWeftAuthorizer`** — the consumer's access hook (`Deny` / `ReadOnly` / `ReadWrite`); Weft never
+  implements identity itself.
+- **`IDocumentStore`** — durable persistence of opaque blobs; `InMemory` / `FileSystem` included,
+  EF Core and Redis adapters in separate packages.
+- Ephemeral awareness/presence, incremental reconnect (state vectors), and per-connection backpressure.
+
+```csharp
+builder.Services.AddWeftServer();
+builder.Services.AddSingleton<IWeftAuthorizer, MyAuthorizer>();
+app.MapWeft("/collab");   // ws://host/collab/{docId}
+```
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+
+Licensed under Apache-2.0.

src/Weft.Server/Weft.Server.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — relay WebSocket y-sync para ASP.NET Core: códec lib0/y-protocols, hook de autorización y persistencia de blobs opacos (IDocumentStore). Compatible con clientes del ecosistema Yjs.</Description>
+    <Description>Weft — y-sync WebSocket relay for ASP.NET Core: lib0/y-protocols codec, an authorization hook, and opaque-blob persistence (IDocumentStore). Compatible with Yjs-ecosystem clients.</Description>
   </PropertyGroup>
 
   <!-- HttpContext (IWeftAuthorizer), WebSockets y el endpoint MapWeft. -->

src/Weft.Versioning/README.md

@@ -0,0 +1,36 @@
+# Weft.Versioning
+
+Engine-agnostic, content-addressed document versioning for .NET: publish immutable versions
+identified by the `SHA-256` of a deterministic export, then diff, branch, merge, and check out — over
+a pluggable blob store.
+
+Part of **[Weft](https://github.com/StrangeDaysTech/weft)** — real-time CRDT collaboration and
+content-addressed document versioning for .NET.
+
+## Install
+
+```bash
+dotnet add package Weft.Versioning   # brings in Weft.Core
+```
+
+## What it provides
+
+- **`VersionStore`** — `PublishAsync` → `VersionId` (same content → same id, always),
+  `CheckoutAsync`, `DiffAsync` (word-level), `BranchAsync`, `Merge`.
+- **`IBlobStore`** — `InMemoryBlobStore`, `FileSystemBlobStore` (per-version, content-addressed,
+  deduplicated). On read it re-hashes and verifies integrity.
+- **Engine-agnostic** — depends only on the `Weft.Core` abstractions, so it runs identically over
+  `yrs` and the optional Loro engine.
+
+```csharp
+var store = new VersionStore(YrsEngine.Instance, new InMemoryBlobStore());
+VersionId v1 = await store.PublishAsync(doc);
+TextDiff diff = await store.DiffAsync(v1, v2, "title");
+```
+
+## Links
+
+- Repository & docs: <https://github.com/StrangeDaysTech/weft>
+- Architecture: <https://github.com/StrangeDaysTech/weft/blob/main/docs/architecture.md>
+
+Licensed under Apache-2.0.

src/Weft.Versioning/Weft.Versioning.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Description>Weft — versionado content-addressed engine-agnóstico (publish/checkout/diff/branch/merge) sobre IBlobStore. Depende solo de las abstracciones de Weft.Core.</Description>
+    <Description>Weft — engine-agnostic content-addressed versioning (publish/checkout/diff/branch/merge) over IBlobStore. Depends only on the Weft.Core abstractions.</Description>
   </PropertyGroup>
 
   <ItemGroup>