diff --git a/README.md b/README.md
new file mode 100644
index 0000000..89d45a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# TX Text Control Document Repository Demo
+
+Razor Pages-style sample (implemented with MVC controllers and views) that showcases how to combine **TX Text Control Web DocumentEditor** with the **TX Text Control Document Repository** SDK. The app lets you create rich-text documents, edit them in the browser, track every version, and download or restore historical revisions from a file-based repository.
+
+## Features
+- Document dashboard with filtering by title/subject, tags, author, and status.
+- Inline status updates (`active`, `draft`, `archived`) plus delete, download, and restore actions for each entry.
+- Deep version history: every save produces a new repository version; previous versions can be restored or opened in the editor.
+- Web-based editing experience powered by `TXTextControl.Web.DocumentEditor` and background worker manager for WebSocket-based synchronization.
+- File-backed repository implementation via `IFileDocumentRepository`, stored in a configurable `DocumentRepository` folder inside the project root.
+
+## Prerequisites
+- [.NET SDK 10](https://dotnet.microsoft.com/download) (Preview at the time of writing).
+- TX Text Control packages referenced in `tx-repo-demo.csproj`:
+  - `TXTextControl.TextControl.Core.SDK`
+  - `TXTextControl.Web`
+  - `TXTextControl.Web.DocumentEditor.Backend`
+- Access to `TXTextControl.DocumentRepository.dll`. The project references it via `<Reference>` with a `HintPath` pointing outside this repo. Adjust the path or place the assembly accordingly. You can clone/build the library from the [TextControl/TXTextControl.DocumentRepository](https://github.com/TextControl/TXTextControl.DocumentRepository) GitHub repo or use the binary that ships with licensed/trial TX Text Control installations.
+
+## Getting Started
+1. **Clone and restore**
+   ```bash
+   git clone https://github.com/TextControl/TXTextControl.DocumentRepository.Demo.git
+   cd TXTextControl.DocumentRepository.Demo/tx-repo-demo
+   dotnet restore
+   ```
+2. **Provide DocumentRepository assets**
+   - Ensure `TXTextControl.DocumentRepository.dll` is reachable at the hint path or update the path in `tx-repo-demo.csproj`. The DLL can be built from [TextControl/TXTextControl.DocumentRepository](https://github.com/TextControl/TXTextControl.DocumentRepository) if you don't already have one.
+   - Create a `DocumentRepository` folder in the project root (same level as `Program.cs`). This folder holds repository metadata and binary content. You can copy existing `.json`/`.tx` data sets from another environment to seed demo data; otherwise it will stay empty until the first document is created.
+3. **Run the site**
+   ```bash
+   dotnet run
+   ```
+   Browse to the HTTPS URL shown in the console (typically `https://localhost:5001`).
+
+## Usage Notes
+- **Creating documents**: Use the *Create New Document* modal on the dashboard. A blank document is generated by `ServerTextControl` and immediately opened in the editor.
+- **Editing**: The `/Edit/Index` view streams repository content into the Web DocumentEditor, and saving uses `SaveToRepositoryAsync` to append a version.
+- **Versioning**: Version history lives under each document row. Restoring calls `RestoreVersionAsync`, preserving the original revision and adding a restoration comment.
+- **Status updates & deletion**: AJAX calls hit `HomeController.UpdateStatus` and `HomeController.Delete` respectively. Both rely on repository APIs and return JSON for client-side feedback.
+- **Data location**: All documents and metadata sit inside the `DocumentRepository` directory. Deleting the folder wipes every stored document, so back up before upgrades or clean-ups.
+
+## Project Structure
+- `Program.cs` wires TX Text Control services, WebSocket middleware, and registers `FileDocumentRepository` that targets the local storage folder.
+- `Controllers/HomeController.cs` renders the dashboard, handles search, version restoration, status changes, downloads, and document creation.
+- `Controllers/EditController.cs` loads specific document versions into the editor and persists new revisions.
+- `Models/*` provide view models for dashboard listings, version details, searches, and the edit surface.
+- `Views/Home/Index.cshtml` contains the dashboard UI, modal forms, and version tables; `Views/Edit/Index.cshtml` hosts the editor surface; shared layout and static assets live under `Views/Shared` and `wwwroot`.
+
+## Troubleshooting
+- **Missing DocumentRepository assembly**: Verify the `<HintPath>` inside `tx-repo-demo.csproj` points to a valid build of `TXTextControl.DocumentRepository.dll` or replace it with a NuGet/ProjectReference once available.
+- **WebSocket issues**: Confirm HTTPS is enabled (default template already configures it) and that `app.UseWebSockets()` plus `app.UseTXWebSocketMiddleware()` remain in the request pipeline.
+- **Empty dashboard**: Ensure the `DocumentRepository` folder exists and the IIS Express/Kestrel worker has write permissions. Creating a new document seeds the repository automatically.
+
+## Next Steps
+- Deploy to IIS or Azure App Service by publishing the project and copying the persisted `DocumentRepository` directory.
+- Extend metadata (e.g., add approval workflow) by augmenting the view models and repository custom properties.
+- Integrate authentication/authorization to replace the placeholder `User.Identity?.Name ?? "Anonymous"` logic.