feat: add Avalonia Zafiro development, layout, and viewmodel skills

skills/avalonia-viewmodels-zafiro/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: avalonia-viewmodels-zafiro
+description: Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI.
+---
+
+# Avalonia ViewModels with Zafiro
+
+This skill provides a set of best practices and patterns for creating ViewModels, Wizards, and managing navigation in Avalonia applications, leveraging the power of **ReactiveUI** and the **Zafiro** toolkit.
+
+## Core Principles
+
+1.  **Functional-Reactive Approach**: Use ReactiveUI (`ReactiveObject`, `WhenAnyValue`, etc.) to handle state and logic.
+2.  **Enhanced Commands**: Utilize `IEnhancedCommand` for better command management, including progress reporting and name/text attributes.
+3.  **Wizard Pattern**: Implement complex flows using `SlimWizard` and `WizardBuilder` for a declarative and maintainable approach.
+4.  **Automatic Section Discovery**: Use the `[Section]` attribute to register and discover UI sections automatically.
+5.  **Clean Composition**: map ViewModels to Views using `DataTypeViewLocator` and manage dependencies in the `CompositionRoot`.
+
+## Guides
+
+- [ViewModels & Commands](viewmodels.md): Creating robust ViewModels and handling commands.
+- [Wizards & Flows](wizards.md): Building multi-step wizards with `SlimWizard`.
+- [Navigation & Sections](navigation_sections.md): Managing navigation and section-based UIs.
+- [Composition & Mapping](composition.md): Best practices for View-ViewModel wiring and DI.
+
+## Example Reference
+
+For real-world implementations, refer to the **Angor** project:
+- `CreateProjectFlowV2.cs`: Excellent example of complex Wizard building.
+- `HomeViewModel.cs`: Simple section ViewModel using functional-reactive commands.

skills/avalonia-viewmodels-zafiro/composition.md

@@ -0,0 +1,75 @@
+# Composition & Mapping
+
+Ensuring your ViewModels are correctly instantiated and mapped to their corresponding Views is crucial for a maintainable application.
+
+## ViewModel-to-View Mapping
+
+Zafiro uses the `DataTypeViewLocator` to automatically map ViewModels to Views based on their data type.
+
+### Integration in App.axaml
+
+Register the `DataTypeViewLocator` in your application's data templates:
+
+```xml
+<Application.DataTemplates>
+    <DataTypeViewLocator />
+    <DataTemplateInclude Source="avares://Zafiro.Avalonia/DataTemplates.axaml" />
+</Application.DataTemplates>
+```
+
+### Registration
+
+Mappings can be registered globally or locally. Common practice in Zafiro projects is to use naming conventions or explicit registrations made by source generators.
+
+## Composition Root
+
+Use a central `CompositionRoot` to manage dependency injection and service registration.
+
+```csharp
+public static class CompositionRoot
+{
+    public static IShellViewModel CreateMainViewModel(Control topLevelView)
+    {
+        var services = new ServiceCollection();
+        
+        services
+            .AddViewModels()
+            .AddUIServices(topLevelView);
+            
+        var serviceProvider = services.BuildServiceProvider();
+        return serviceProvider.GetRequiredService<IShellViewModel>();
+    }
+}
+```
+
+### Registering ViewModels
+
+Register ViewModels with appropriate scopes (Transient, Scoped, or Singleton).
+
+```csharp
+public static IServiceCollection AddViewModels(this IServiceCollection services)
+{
+    return services
+        .AddTransient<IHomeSectionViewModel, HomeSectionSectionViewModel>()
+        .AddSingleton<IShellViewModel, ShellViewModel>();
+}
+```
+
+## View Injection
+
+Use the `Connect` helper (if available) or manual instantiation in `OnFrameworkInitializationCompleted`:
+
+```csharp
+public override void OnFrameworkInitializationCompleted()
+{
+    this.Connect(
+        () => new ShellView(),
+        view => CompositionRoot.CreateMainViewModel(view),
+        () => new MainWindow());
+
+    base.OnFrameworkInitializationCompleted();
+}
+```
+
+> [!TIP]
+> Use `ActivatorUtilities.CreateInstance` when you need to manually instantiate a class while still resolving its dependencies from the `IServiceProvider`.

skills/avalonia-viewmodels-zafiro/navigation_sections.md

@@ -0,0 +1,53 @@
+# Navigation & Sections
+
+Zafiro provides powerful abstractions for managing application-wide navigation and modular UI sections.
+
+## Navigation with INavigator
+
+The `INavigator` interface is used to switch between different views or viewmodels.
+
+```csharp
+public class MyViewModel(INavigator navigator)
+{
+    public async Task GoToDetails()
+    {
+        await navigator.Navigate(() => new DetailsViewModel());
+    }
+}
+```
+
+## UI Sections
+
+Sections are modular parts of the UI (like tabs or sidebar items) that can be automatically registered.
+
+### The [Section] Attribute
+
+ViewModels intended to be sections should be marked with the `[Section]` attribute.
+
+```csharp
+[Section("Wallet", icon: "fa-wallet")]
+public class WalletSectionViewModel : IWalletSectionViewModel
+{
+    // ...
+}
+```
+
+### Automatic Registration
+
+In the `CompositionRoot`, sections can be automatically registered:
+
+```csharp
+services.AddAnnotatedSections(logger);
+services.AddSectionsFromAttributes(logger);
+```
+
+### Switching Sections
+
+You can switch the current active section via the `IShellViewModel`:
+
+```csharp
+shellViewModel.SetSection("Browse");
+```
+
+> [!IMPORTANT]
+> The `icon` parameter in the `[Section]` attribute supports FontAwesome icons (e.g., `fa-home`) when configured with `ProjektankerIconControlProvider`.

skills/avalonia-viewmodels-zafiro/viewmodels.md

@@ -0,0 +1,68 @@
+# ViewModels & Commands
+
+In a Zafiro-based application, ViewModels should be functional, reactive, and resilient.
+
+## Reactive ViewModels
+
+Use `ReactiveObject` as the base class. Properties should be defined using the `[Reactive]` attribute (from ReactiveUI.SourceGenerators) for brevity.
+
+```csharp
+public partial class MyViewModel : ReactiveObject
+{
+    [Reactive] private string name;
+    [Reactive] private bool isBusy;
+}
+```
+
+### Observation and Transformation
+
+Use `WhenAnyValue` to react to property changes:
+
+```csharp
+this.WhenAnyValue(x => x.Name)
+    .Select(name => !string.IsNullOrEmpty(name))
+    .ToPropertyEx(this, x => x.CanSubmit);
+```
+
+## Enhanced Commands
+
+Zafiro uses `IEnhancedCommand`, which extends `ICommand` and `IReactiveCommand` with additional metadata like `Name` and `Text`.
+
+### Creating a Command
+
+Use `ReactiveCommand.Create` or `ReactiveCommand.CreateFromTask` and then `Enhance()` it.
+
+```csharp
+public IEnhancedCommand Submit { get; }
+
+public MyViewModel()
+{
+    Submit = ReactiveCommand.CreateFromTask(OnSubmit, canSubmit)
+        .Enhance(text: "Submit Data", name: "SubmitCommand");
+}
+```
+
+### Error Handling
+
+Use `HandleErrorsWith` to automatically channel command errors to the `NotificationService`.
+
+```csharp
+Submit.HandleErrorsWith(uiServices.NotificationService, "Submission Failed")
+    .DisposeWith(disposable);
+```
+
+## Disposables
+
+Always use a `CompositeDisposable` to manage subscriptions and command lifetimes.
+
+```csharp
+public class MyViewModel : ReactiveObject, IDisposable
+{
+    private readonly CompositeDisposable disposables = new();
+
+    public void Dispose() => disposables.Dispose();
+}
+```
+
+> [!TIP]
+> Use `.DisposeWith(disposables)` on any observable subscription or command to ensure proper cleanup.

skills/avalonia-viewmodels-zafiro/wizards.md

@@ -0,0 +1,47 @@
+# Wizards & Flows
+
+Complex multi-step processes are handled using the `SlimWizard` pattern. This provides a declarative way to define steps, navigation logic, and final results.
+
+## Defining a Wizard
+
+Use `WizardBuilder` to define the steps. Each step corresponds to a ViewModel.
+
+```csharp
+SlimWizard<string> wizard = WizardBuilder
+    .StartWith(() => new Step1ViewModel(data))
+        .NextUnit()
+        .WhenValid()
+    .Then(prevResult => new Step2ViewModel(prevResult))
+        .NextCommand(vm => vm.CustomNextCommand)
+    .Then(result => new SuccessViewModel("Done!"))
+        .Next((_, s) => s, "Finish")
+    .WithCompletionFinalStep();
+```
+
+### Navigation Rules
+
+- **NextUnit()**: Advances when a simple signal is emitted.
+- **NextCommand()**: Advances when a specific command in the ViewModel execution successfully.
+- **WhenValid()**: Wait until the current ViewModel's validation passes before allowing navigation.
+- **Always()**: Navigation is always allowed.
+
+## Navigation Integration
+
+The wizard is navigated using an `INavigator`:
+
+```csharp
+public async Task CreateSomething()
+{
+    var wizard = BuildWizard();
+    var result = await wizard.Navigate(navigator);
+    // Handle result
+}
+```
+
+## Step Configuration
+
+- **WithCompletionFinalStep()**: Marks the wizard as finished when the last step completes.
+- **WithCommitFinalStep()**: Typically used for wizards that perform a final "Save" or "Deploy" action.
+
+> [!NOTE]
+> The `SlimWizard` handles the "Back" command automatically, providing a consistent user experience across different flows.