From 52d074510e8940812659e108337b888cd1fdd4a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?=
 <195970+montfort@users.noreply.github.com>
Date: Sun, 19 Jul 2026 11:24:51 -0600
Subject: [PATCH] docs(packaging): per-package READMEs + English descriptions
 for NuGet

The published 1.0.0 packages showed no README and a Spanish <Description>
(a residue of the English migration that lived in the .csproj, not a
comment). Fix both in the package metadata so the next release (1.0.1)
ships correct, embedded content.

- Directory.Build.props: PackageReadmeFile=README.md + pack each publishable
  library's own README.md into its .nupkg.
- Six per-package README.md (Core, Versioning, Server, Loro,
  Persistence.EFCore, Persistence.Redis): what it provides, install, a short
  snippet, links (absolute URLs so they resolve on nuget.org).
- Translated the six <Description> values to English.

Verified: dotnet pack embeds README.md (<readme> in the .nuspec) and the
English description; markdownlint clean; build green. 1.0.0 packages are
immutable, so this lands in 1.0.1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 Directory.Build.props                         |  9 ++++-
 src/Weft.Core/README.md                       | 33 +++++++++++++++++
 src/Weft.Core/Weft.Core.csproj                |  2 +-
 src/Weft.Loro/README.md                       | 34 ++++++++++++++++++
 src/Weft.Loro/Weft.Loro.csproj                |  2 +-
 src/Weft.Server.Persistence.EFCore/README.md  | 29 +++++++++++++++
 .../Weft.Server.Persistence.EFCore.csproj     |  2 +-
 src/Weft.Server.Persistence.Redis/README.md   | 28 +++++++++++++++
 .../Weft.Server.Persistence.Redis.csproj      |  2 +-
 src/Weft.Server/README.md                     | 35 ++++++++++++++++++
 src/Weft.Server/Weft.Server.csproj            |  2 +-
 src/Weft.Versioning/README.md                 | 36 +++++++++++++++++++
 src/Weft.Versioning/Weft.Versioning.csproj    |  2 +-
 13 files changed, 209 insertions(+), 7 deletions(-)
 create mode 100644 src/Weft.Core/README.md
 create mode 100644 src/Weft.Loro/README.md
 create mode 100644 src/Weft.Server.Persistence.EFCore/README.md
 create mode 100644 src/Weft.Server.Persistence.Redis/README.md
 create mode 100644 src/Weft.Server/README.md
 create mode 100644 src/Weft.Versioning/README.md

diff --git a/Directory.Build.props b/Directory.Build.props
index ea33ab3..3e08531 100644
--- a/Directory.Build.props
+++ b/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>
diff --git a/src/Weft.Core/README.md b/src/Weft.Core/README.md
new file mode 100644
index 0000000..7ed0598
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Core/Weft.Core.csproj b/src/Weft.Core/Weft.Core.csproj
index ab4682b..cf6bb22 100644
--- a/src/Weft.Core/Weft.Core.csproj
+++ b/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). -->
diff --git a/src/Weft.Loro/README.md b/src/Weft.Loro/README.md
new file mode 100644
index 0000000..1c1703f
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Loro/Weft.Loro.csproj b/src/Weft.Loro/Weft.Loro.csproj
index 0b9daa0..fb868bd 100644
--- a/src/Weft.Loro/Weft.Loro.csproj
+++ b/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>
diff --git a/src/Weft.Server.Persistence.EFCore/README.md b/src/Weft.Server.Persistence.EFCore/README.md
new file mode 100644
index 0000000..af5fa6c
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Server.Persistence.EFCore/Weft.Server.Persistence.EFCore.csproj b/src/Weft.Server.Persistence.EFCore/Weft.Server.Persistence.EFCore.csproj
index f6c08ee..e646c19 100644
--- a/src/Weft.Server.Persistence.EFCore/Weft.Server.Persistence.EFCore.csproj
+++ b/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>
 
diff --git a/src/Weft.Server.Persistence.Redis/README.md b/src/Weft.Server.Persistence.Redis/README.md
new file mode 100644
index 0000000..7479a27
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Server.Persistence.Redis/Weft.Server.Persistence.Redis.csproj b/src/Weft.Server.Persistence.Redis/Weft.Server.Persistence.Redis.csproj
index 135fb4b..7d64f0f 100644
--- a/src/Weft.Server.Persistence.Redis/Weft.Server.Persistence.Redis.csproj
+++ b/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>
 
diff --git a/src/Weft.Server/README.md b/src/Weft.Server/README.md
new file mode 100644
index 0000000..c4edf89
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Server/Weft.Server.csproj b/src/Weft.Server/Weft.Server.csproj
index aafa74a..32821a2 100644
--- a/src/Weft.Server/Weft.Server.csproj
+++ b/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. -->
diff --git a/src/Weft.Versioning/README.md b/src/Weft.Versioning/README.md
new file mode 100644
index 0000000..06a250c
--- /dev/null
+++ b/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.
diff --git a/src/Weft.Versioning/Weft.Versioning.csproj b/src/Weft.Versioning/Weft.Versioning.csproj
index 5aadb42..0e86642 100644
--- a/src/Weft.Versioning/Weft.Versioning.csproj
+++ b/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>