docs: document Pinget distribution packages

.agents/skills/.gitkeep

@@ -0,0 +1 @@
+Placeholder for shared agent skills.

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

AGENTS.md

@@ -8,13 +8,11 @@ This directory is being prepared to become its own `pinget` repository. Treat `p
 - Maintain the C# CLI + core + PowerShell module in `dotnet\`
 - Keep **both** `rust\` and `dotnet\` directories in the standalone-repo prep
 - Keep behavior aligned with WinGet where practical
-- Keep the implementation **COM-free**
 
 ## Hard exclusions
 
 Do not add or depend on:
 
-- COM / WinRT / `Microsoft.Management.Deployment`
 - DSC / `configure` / `dscv3` / `Microsoft.WinGet.Configuration`
 - `mcp`
 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -27,13 +27,156 @@ Structured manifest output is also supported:
 - `show --output json|yaml`
 - `search --manifests --output json|yaml`
 
-The C# implementation also ships the **`Devolutions.Pinget.Client` PowerShell 7 module** that mirrors the upstream `Microsoft.WinGet.Client` cmdlet family with renamed `Pinget` nouns, backed entirely by `Devolutions.Pinget.Core` rather than COM / WinRT APIs.
+The C# implementation also ships the **`Devolutions.Pinget.Client` PowerShell 7 module** that mirrors the upstream `Microsoft.WinGet.Client` cmdlet family with renamed `Pinget` nouns, backed by `Devolutions.Pinget.Core`.
+
+## Pinget CLI
+
+The prebuilt `pinget` CLI published in [GitHub Releases](https://github.com/Devolutions/pinget/releases) is the Rust build. Download the archive for your platform, extract it, and put the `pinget` executable on your `PATH`.
+
+```powershell
+pinget --help
+pinget --info
+pinget source list
+pinget source update
+```
+
+Examples below use Devolutions packages from the community WinGet manifests:
+
+```powershell
+# Discover packages.
+pinget search Devolutions
+pinget search --id Devolutions.RemoteDesktopManager --exact
+pinget search --id Devolutions.MsRdpEx --exact --versions
+
+# Inspect package metadata.
+pinget show --id Devolutions.RemoteDesktopManager --exact
+pinget show --id Devolutions.MsRdpEx --exact --versions
+
+# Produce structured manifest output for automation.
+pinget show --id Devolutions.RemoteDesktopManager --exact --output json
+pinget search Devolutions --manifests --output yaml
+
+# Download installers without installing them.
+pinget download --id Devolutions.RemoteDesktopManager --download-directory .\downloads
+
+# Query installed packages and available upgrades.
+pinget list Devolutions
+pinget upgrade
+
+# Package action commands execute installers on supported platforms.
+pinget install --id Devolutions.MsRdpEx --scope user --silent
+pinget uninstall --id Devolutions.MsRdpEx --silent
+```
+
+## PowerShell module
+
+The **`Devolutions.Pinget.Client`** module is available from the PowerShell Gallery:
+
+```powershell
+# Recommended for current PowerShellGet/PSResourceGet environments.
+Install-PSResource -Name Devolutions.Pinget.Client -Repository PSGallery
+
+# PowerShellGet v2 alternative.
+Install-Module -Name Devolutions.Pinget.Client -Scope CurrentUser
+```
+
+The module requires PowerShell 7.4 or later and exposes WinGet-style cmdlets with `Pinget` nouns instead of `WinGet` nouns. It is implemented over `Devolutions.Pinget.Core`.
+
+```powershell
+Import-Module Devolutions.Pinget.Client
+
+Get-PingetVersion
+Get-Command -Module Devolutions.Pinget.Client
+Get-PingetSource
+```
+
+Examples below use Devolutions packages from the community WinGet manifests:
+
+```powershell
+# Discover Devolutions packages.
+Find-PingetPackage -Query Devolutions
+Find-PingetPackage -Id Devolutions.RemoteDesktopManager
+Find-PingetPackage -Id Devolutions.MsRdpEx
+
+# Inspect package metadata and available versions.
+$rdm = Find-PingetPackage -Id Devolutions.RemoteDesktopManager | Select-Object -First 1
+$rdm.AvailableVersions | Select-Object -First 5
+$rdm.GetPackageVersionInfo($rdm.AvailableVersions[0]) |
+    Format-List Id, DisplayName, Version, Publisher, InstallerType, InstallerUrl
+
+# Query installed packages.
+Get-PingetPackage -Name Devolutions
+Get-PingetPackage -Id Devolutions.RemoteDesktopManager
+
+# Preview package operations. Remove -WhatIf to execute them.
+Install-PingetPackage -Id Devolutions.MsRdpEx -Scope User -WhatIf
+Update-PingetPackage -Id Devolutions.RemoteDesktopManager -WhatIf
+Uninstall-PingetPackage -Id Devolutions.MsRdpEx -WhatIf
+
+# Download installers without installing them.
+Export-PingetPackage -Id Devolutions.RemoteDesktopManager -DownloadDirectory .\downloads
+```
+
+Useful exported cmdlets include `Find-PingetPackage`, `Get-PingetPackage`, `Install-PingetPackage`, `Update-PingetPackage`, `Uninstall-PingetPackage`, `Repair-PingetPackage`, `Export-PingetPackage`, `Get-PingetSource`, `Add-PingetSource`, `Remove-PingetSource`, `Reset-PingetSource`, and the user-setting cmdlets.
+
+## NuGet package
+
+The **`Devolutions.Pinget.Core`** library is available on [nuget.org](https://www.nuget.org/packages/Devolutions.Pinget.Core) for .NET applications that want to use Pinget package discovery, source caches, manifest metadata, downloads, and installed package state programmatically.
+
+```powershell
+dotnet add package Devolutions.Pinget.Core
+```
+
+The package targets .NET 8 and .NET 10. `Repository.Open()` is the main entry point; pass `RepositoryOptions` when you want an isolated app root or a custom user agent.
+
+```csharp
+using Devolutions.Pinget.Core;
+
+using var repository = Repository.Open(new RepositoryOptions
+{
+    AppRoot = Path.Combine(Path.GetTempPath(), "pinget-sample"),
+    UserAgent = "my-app/1.0",
+});
+
+foreach (var update in repository.UpdateSources())
+{
+    Console.WriteLine($"{update.Name}: {update.Detail}");
+}
+
+var search = repository.Search(new PackageQuery
+{
+    Query = "Devolutions",
+    Count = 10,
+});
+
+foreach (var package in search.Matches)
+{
+    Console.WriteLine($"{package.Id} {package.Version}");
+}
+
+var rdm = repository.Show(new PackageQuery
+{
+    Id = "Devolutions.RemoteDesktopManager",
+    Exact = true,
+});
+
+Console.WriteLine($"{rdm.Manifest.Name} {rdm.Manifest.Version}");
+
+var (_, installerPath) = repository.DownloadInstaller(
+    new PackageQuery
+    {
+        Id = "Devolutions.MsRdpEx",
+        Exact = true,
+    },
+    Path.Combine(Environment.CurrentDirectory, "downloads"));
+
+Console.WriteLine(installerPath);
+```
 
 ## Non-goals
 
 Pinget intentionally excludes:
 
-- COM / WinRT / `Microsoft.Management.Deployment`
 - DSC-backed configuration flows (`configure`, `dscv3`, `Microsoft.WinGet.Configuration`)
 - `mcp`
 
@@ -126,7 +269,7 @@ Pinget is maintained with WinGet compatibility in mind. Current prep rules:
 
 1. Prefer subtree-relative paths in docs and scripts.
 2. Keep Pinget-specific documentation under this directory instead of the parent repo when practical.
-3. Avoid introducing dependencies on the native WinGet COM stack, DSC/configuration stack, or MCP.
+3. Avoid introducing dependencies on the native WinGet DSC/configuration stack or MCP.
 4. Keep Rust and C# toolchain instructions runnable from this directory as a future repository root.
 
 ## Status
@@ -137,6 +280,6 @@ Pinget is best treated as an **experimental portable winget implementation** foc
 - manifest retrieval and shaping
 - custom REST source support
 - reusable library surfaces in Rust and C#
-- a COM-free PowerShell automation surface over the C# implementation
+- a PowerShell automation surface over the C# implementation
 
 It is not intended to be a drop-in, fully complete replacement for the native Windows Package Manager client.