big renaming

Author: KSemenenko

AGENTS.md

@@ -0,0 +1,36 @@
+# Conversations
+any resulting updates to agents.md should go under the section "## Rules to follow"
+When you see a convincing argument from me on how to solve or do something. add a summary for this in agents.md. so you learn what I want over time.
+If I say any of the following point, you do this: add the context to agents.md, and associate this with a specific type of task.
+if I say "never do x" in some way.
+if I say "always do x" in some way.
+if I say "the process is x" in some way.
+If I tell you to remember something, you do the same, update
+
+
+## Rules to follow
+- MIME handling: always use `ManagedCode.MimeTypes` for MIME constants, lookups, and validation logic.
+
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`MarkItDown.slnx` stitches together the core library under `src/MarkItDown` and the CLI scaffold in `src/MarkItDown.Cli`. The `MarkItDown` project hosts converters, options, and MIME helpers; keep new format handlers inside `Converters/` with focused folders. Integration and regression tests live in `tests/MarkItDown.Tests`, using `*Tests.cs` naming. The `microsoft-markitdown` directory mirrors the upstream Python project via submodule—update it only when syncing parity fixtures. Generated `bin/`, `obj/`, and `TestResults/` folders appear locally; avoid committing them.
+
+## Build, Test, and Development Commands
+- `dotnet restore MarkItDown.slnx` – hydrate solution-wide dependencies.
+- `dotnet build MarkItDown.slnx` – compile all projects with analyzers enforced.
+- `dotnet test MarkItDown.slnx` – run xUnit suites; fails on warnings because of solution settings.
+- `dotnet test MarkItDown.slnx --collect:"XPlat Code Coverage"` – emit Cobertura XML under `tests/MarkItDown.Tests/TestResults/`.
+- `dotnet run --project src/MarkItDown.Cli -- sample.pdf` – try the CLI (currently experimental) against a local asset.
+
+## Coding Style & Naming Conventions
+Projects target `net9.0`, `LangVersion` 13, `Nullable` enabled, and treat warnings as errors. Follow standard C# layout: four-space indents, braces on new lines, and `PascalCase` for types/methods, `camelCase` for locals and parameters. Prefer expression-bodied members only when they improve clarity. Use `var` when the right-hand side makes the type obvious. Keep XML documentation on public APIs and log messages actionable.
+
+## Testing Guidelines
+Tests use xUnit with Shouldly helpers; place fixtures alongside the code they cover. Name methods `MethodUnderTest_Scenario_Expectation` to match existing suites. When adding new converters, create integration tests under `tests/MarkItDown.Tests` that ensure round-trip Markdown and negative paths. Collect coverage with the command above and review the generated Cobertura report before submitting.
+
+## Commit & Pull Request Guidelines
+Recent history favors short, lower-case commit subjects (for example, `removecli`). Continue with concise, descriptive imperatives, optionally tagging scopes (`converter: add epub caption support`). Each PR should link related issues, outline behaviour changes, and note test or coverage results. Attach CLI output or screenshots when UX-facing changes occur, and call out any parity updates pulled from the Python submodule.
+
+## Security & Configuration Notes
+Respect `.gitmodules` and `Directory.Build.props`—they embed repository URLs, reproducible build settings, and authorship data. Never check in API keys or document samples that contain customer data. Configuration overrides belong in `MarkItDownOptions`; guard new options with sensible defaults to keep the library safe for unattended execution.

Directory.Build.props

@@ -21,8 +21,8 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <Product>Managed Code - MarkItDown</Product>
-    <Version>0.0.1</Version>
-    <PackageVersion>0.0.1</PackageVersion>
+    <Version>0.0.2</Version>
+    <PackageVersion>0.0.2</PackageVersion>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">

MarkItDown.slnx

@@ -5,9 +5,9 @@
     <Platform Name="x86" />
   </Configurations>
   <Folder Name="/src/">
-    <Project Path="src/MarkItDown.Core/MarkItDown.Core.csproj" />
+    <Project Path="src\MarkItDown\MarkItDown.csproj" />
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/MarkItDown.Tests/MarkItDown.Tests.csproj" />
   </Folder>
-</Solution>
+</Solution>

README.md

@@ -169,73 +169,105 @@ dotnet add package ManagedCode.MarkItDown
 
 ## 💻 Usage
 
-### Basic API Usage
+### Convert a local file
 
 ```csharp
-using MarkItDown.Core;
+using MarkItDown;
 
-// Simple conversion
+// Convert a DOCX file and print the Markdown
 var markItDown = new MarkItDown();
-var result = await markItDown.ConvertAsync("document.html");
+DocumentConverterResult result = await markItDown.ConvertAsync("report.docx");
 Console.WriteLine(result.Markdown);
 ```
 
-### Advanced Usage with Logging
+### Convert a stream with metadata overrides
 
 ```csharp
-using MarkItDown.Core;
-using Microsoft.Extensions.Logging;
+using System.IO;
+using System.Text;
+using MarkItDown;
+
+using var stream = File.OpenRead("invoice.html");
+var streamInfo = new StreamInfo(
+    mimeType: "text/html",
+    extension: ".html",
+    charset: Encoding.UTF8,
+    fileName: "invoice.html");
 
-// With logging and HTTP client for web content
-using var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
-var logger = loggerFactory.CreateLogger<Program>();
+var markItDown = new MarkItDown();
+var result = await markItDown.ConvertAsync(stream, streamInfo);
+Console.WriteLine(result.Title);
+```
+
+### Convert content from HTTP/HTTPS
+
+```csharp
+using MarkItDown;
+using Microsoft.Extensions.Logging;
 
+using var loggerFactory = LoggerFactory.Create(static builder => builder.AddConsole());
 using var httpClient = new HttpClient();
-var markItDown = new MarkItDown(logger, httpClient);
 
-// Convert from file
-var fileResult = await markItDown.ConvertAsync("document.html");
+var markItDown = new MarkItDown(
+    logger: loggerFactory.CreateLogger<MarkItDown>(),
+    httpClient: httpClient);
+
+DocumentConverterResult urlResult = await markItDown.ConvertFromUrlAsync("https://contoso.example/blog");
+Console.WriteLine(urlResult.Title);
+```
 
-// Convert from URL
-var urlResult = await markItDown.ConvertFromUrlAsync("https://example.com");
+### Customise the pipeline with options
 
-// Convert from URI (file:, data:, http:, https:)
-var dataResult = await markItDown.ConvertUriAsync("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=");
+```csharp
+using Azure;
+using MarkItDown;
+
+var options = new MarkItDownOptions
+{
+    // Plug in your own services (Azure AI, OpenAI, etc.)
+    ImageCaptioner = async (bytes, info, token) =>
+        await myCaptionService.DescribeAsync(bytes, info, token),
+    AudioTranscriber = async (bytes, info, token) =>
+        await speechClient.TranscribeAsync(bytes, info, token),
+    DocumentIntelligence = new DocumentIntelligenceOptions
+    {
+        Endpoint = "https://<your-resource>.cognitiveservices.azure.com/",
+        Credential = new AzureKeyCredential("<document-intelligence-key>")
+    }
+};
 
-// Convert from stream with optional overrides
-using var stream = File.OpenRead("document.html");
-var streamInfo = new StreamInfo(mimeType: "text/html", extension: ".html");
-var streamResult = await markItDown.ConvertAsync(stream, streamInfo);
+var markItDown = new MarkItDown(options);
 ```
 
-### Custom Converters
+### Custom converters
 
 Create your own format converters by implementing `IDocumentConverter`:
 
 ```csharp
-using MarkItDown.Core;
+using System.IO;
+using MarkItDown;
 
-public class MyCustomConverter : IDocumentConverter
+public sealed class MyCustomConverter : IDocumentConverter
 {
-    public bool Accepts(Stream stream, StreamInfo streamInfo, CancellationToken cancellationToken = default)
-    {
-        return streamInfo.Extension == ".mycustomformat";
-    }
+    public int Priority => ConverterPriority.SpecificFileFormat;
+
+    public bool AcceptsInput(StreamInfo streamInfo) =>
+        string.Equals(streamInfo.Extension, ".mycustom", StringComparison.OrdinalIgnoreCase);
 
-    public async Task<DocumentConverterResult> ConvertAsync(
-        Stream stream, 
-        StreamInfo streamInfo, 
+    public Task<DocumentConverterResult> ConvertAsync(
+        Stream stream,
+        StreamInfo streamInfo,
         CancellationToken cancellationToken = default)
     {
-        // Your conversion logic here
-        var markdown = "# Converted from custom format\n\nContent here...";
-        return new DocumentConverterResult(markdown, "Document Title");
+        stream.Seek(0, SeekOrigin.Begin);
+        using var reader = new StreamReader(stream, leaveOpen: true);
+        var markdown = "# Converted from custom format\n\n" + reader.ReadToEnd();
+        return Task.FromResult(new DocumentConverterResult(markdown, "Custom document"));
     }
 }
 
-// Register the custom converter
 var markItDown = new MarkItDown();
-markItDown.RegisterConverter(new MyCustomConverter(), ConverterPriority.SpecificFileFormat);
+markItDown.RegisterConverter(new MyCustomConverter());
 ```
 
 ## 🏗️ Architecture
@@ -287,16 +319,28 @@ dotnet test
 dotnet pack --configuration Release
 ```
 
+### Tests & Coverage
+
+```bash
+dotnet test --collect:"XPlat Code Coverage"
+```
+
+The command emits standard test results plus a Cobertura coverage report at
+`tests/MarkItDown.Tests/TestResults/<guid>/coverage.cobertura.xml`. Tools such as
+[ReportGenerator](https://github.com/danielpalme/ReportGenerator) can turn this into
+HTML or Markdown dashboards.
+
 ### Project Structure
 
 ```
 ├── src/
-│   ├── MarkItDown.Core/           # Core library
+│   ├── MarkItDown/                # Core library
 │   │   ├── Converters/            # Format-specific converters (HTML, PDF, audio, etc.)
 │   │   ├── MarkItDown.cs          # Main conversion engine
 │   │   ├── StreamInfoGuesser.cs   # MIME/charset/extension detection helpers
 │   │   ├── MarkItDownOptions.cs   # Runtime configuration flags
 │   │   └── ...                    # Shared utilities (UriUtilities, MimeMapping, etc.)
+│   └── MarkItDown.Cli/            # CLI host (under active development)
 ├── tests/
 │   └── MarkItDown.Tests/          # xUnit + Shouldly tests, Python parity vectors (WIP)
 ├── Directory.Build.props          # Shared build + packaging settings