feat: polishing ui improvements and system prompts

Author: Piotr Stachaczynski

backend/MaIN.Docs.Api/Models/CapacitySettings.cs

@@ -3,9 +3,10 @@ namespace MaIN.Docs.Api.Models;
 public record CapacitySettings(
     Tier1Settings Tier1,
     Tier2Settings Tier2,
-    Tier3Settings Tier3)
+    Tier3Settings Tier3,
+    string ReasoningEffort = "")
 {
-    public CapacitySettings() : this(new Tier1Settings(), new Tier2Settings(), new Tier3Settings()) { }
+    public CapacitySettings() : this(new Tier1Settings(), new Tier2Settings(), new Tier3Settings(), "") { }
 }
 
 public record Tier1Settings(long TokenLimit = 150_000, int CooldownMinutes = 180)

backend/MaIN.Docs.Api/Models/ModelSettings.cs

@@ -0,0 +1,28 @@
+namespace MaIN.Docs.Api.Models;
+
+public record ModelSettings(
+    Tier1ModelSettings Tier1,
+    Tier2ModelSettings Tier2)
+{
+    public ModelSettings() : this(new Tier1ModelSettings(), new Tier2ModelSettings()) { }
+}
+
+public record Tier1ModelSettings(
+    string Chatty = "gemini-3.1-flash-lite",
+    string Code = "gemini-3.5-flash",
+    string Review = "gemini-3.5-flash",
+    string Design = "gemini-3.1-pro-preview",
+    string Forge = "gemini-3.1-pro-preview")
+{
+    public Tier1ModelSettings() : this("gemini-3.1-flash-lite", "gemini-3.5-flash", "gemini-3.5-flash", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview") { }
+}
+
+public record Tier2ModelSettings(
+    string Chatty = "gemini-3.1-flash-lite",
+    string Code = "gemini-3.1-flash-lite",
+    string Review = "gemini-3.1-flash-lite",
+    string Design = "gemini-3.1-flash-lite",
+    string Forge = "gemini-3.1-flash-lite")
+{
+    public Tier2ModelSettings() : this("gemini-3.1-flash-lite", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite") { }
+}

backend/MaIN.Docs.Api/Program.cs

@@ -43,6 +43,7 @@
 });
 
 builder.Services.Configure<CapacitySettings>(builder.Configuration.GetSection("Capacity"));
+builder.Services.Configure<ModelSettings>(builder.Configuration.GetSection("Models"));
 builder.Services.AddSingleton<CapacityStateStore>();
 builder.Services.AddSingleton<CapacityService>();
 builder.Services.AddHostedService<CapacityPersistenceService>();

backend/MaIN.Docs.Api/Services/DocsAgentOrchestrator.cs

@@ -11,7 +11,6 @@
 using MaIN.Domain.Models.Abstract;
 using MaIN.Docs.Api.Models;
 using Microsoft.Extensions.Options;
-using DomainModels = MaIN.Domain.Models.Models;
 
 namespace MaIN.Docs.Api.Services;
 
@@ -21,6 +20,7 @@ public class DocsAgentOrchestrator(
     GitHubService githubService,
     CapacityService capacityService,
     IOptions<CapacitySettings> capacityOptions,
+    IOptions<ModelSettings> modelOptions,
     IConfiguration configuration,
     ILogger<DocsAgentOrchestrator> logger)
 {
@@ -44,6 +44,7 @@ private async Task InitializeForTierAsync(int tier)
         PrTools.Init(githubService);
 
         var settings = capacityOptions.Value;
+        var models = modelOptions.Value;
         var geminiKey1 = configuration["MaIN:GeminiKey"] ?? "";
 
         string modelChatty, modelCode, modelReview, modelDesign, modelForge;
@@ -81,11 +82,11 @@ private async Task InitializeForTierAsync(int tier)
                 cfg.BackendType = BackendType.Gemini;
                 cfg.GeminiKey   = settings.Tier2.GeminiKey;
             });
-            modelChatty = DomainModels.Gemini.Gemini3_1FlashLite;
-            modelCode   = DomainModels.Gemini.Gemini3_1FlashLite;
-            modelReview = DomainModels.Gemini.Gemini3_1FlashLite;
-            modelDesign = DomainModels.Gemini.Gemini3_1FlashLite;
-            modelForge  = DomainModels.Gemini.Gemini3_1FlashLite;
+            modelChatty = models.Tier2.Chatty;
+            modelCode   = models.Tier2.Code;
+            modelReview = models.Tier2.Review;
+            modelDesign = models.Tier2.Design;
+            modelForge  = models.Tier2.Forge;
             logger.LogInformation("[Capacity] Initializing agents for Tier 2 (low) — Flash Lite on secondary key");
         }
         else
@@ -95,11 +96,11 @@ private async Task InitializeForTierAsync(int tier)
                 cfg.BackendType = BackendType.Gemini;
                 cfg.GeminiKey   = geminiKey1;
             });
-            modelChatty = DomainModels.Gemini.Gemini3_1FlashLite;
-            modelCode   = DomainModels.Gemini.Gemini3_5Flash;
-            modelReview = DomainModels.Gemini.Gemini3_5Flash;
-            modelDesign = DomainModels.Gemini.Gemini3_1ProPreview;
-            modelForge  = DomainModels.Gemini.Gemini3_1ProPreview;
+            modelChatty = models.Tier1.Chatty;
+            modelCode   = models.Tier1.Code;
+            modelReview = models.Tier1.Review;
+            modelDesign = models.Tier1.Design;
+            modelForge  = models.Tier1.Forge;
             logger.LogInformation("[Capacity] Initializing agents for Tier 1 (normal) — standard Gemini stack");
         }
 
@@ -108,7 +109,13 @@ private async Task InitializeForTierAsync(int tier)
         // output. With no MaxTokens set, that budget can be exhausted entirely by reasoning
         // across multi-step tool-call turns, leaving both Content and the FullAnswer token
         // empty. Give every Gemini-backed agent more headroom.
-        var geminiParams = tier < 3 ? new GeminiInferenceParams { MaxTokens = 16384 } : null;
+        var geminiAdditionalParams = new Dictionary<string, object>();
+        if (!string.IsNullOrWhiteSpace(settings.ReasoningEffort))
+            geminiAdditionalParams["reasoning_effort"] = settings.ReasoningEffort;
+
+        var geminiParams = tier < 3
+            ? new GeminiInferenceParams { MaxTokens = 16384, AdditionalParams = geminiAdditionalParams }
+            : null;
 
         var chattyTools  = BuildChattyTools(docsPath);
         var codeTools    = BuildCodeTools(docsPath);
@@ -234,6 +241,8 @@ public async Task<AgentResult> ProcessAsync(
             docsRead.Add(path);
             toolResultChars += contentLength;
         });
+        var readPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        MdTools.SetReadDedup(readPaths);
 
         if (agentId == "code")
         {
@@ -373,6 +382,7 @@ async Task<AgentResult> Core(IAgentContextExecutor agentCtx)
 
                 docsRead.Clear();
                 toolResultChars = 0;
+                readPaths.Clear();
                 artifactUrl = null; artifactProposed = null;
                 issueUrl = null; issueProposed = null; planProposed = null;
                 reviewProposed = null; reviewPosted = null; codeChangeProposed = null;
@@ -397,6 +407,7 @@ async Task<AgentResult> Core(IAgentContextExecutor agentCtx)
             PrTools.SetPrCapture(null);
             PrTools.SetPrUrlCapture(null);
             MdTools.SetReadCapture(null);
+            MdTools.SetReadDedup(null);
             sem.Release();
         }
     }
@@ -865,7 +876,7 @@ private static ToolsConfiguration BuildCodeTools(string docsPath) =>
                     required = new[] { "archiveName", "description", "kind" }
                 },
                 ArtifactTools.Propose)
-            .WithMaxIterations(10)
+            .WithMaxIterations(18)
             .WithToolChoice("auto")
             .Build();
 
@@ -1243,7 +1254,10 @@ FRAMEWORK FACTS (don't guess, verify via tools):
         - Console bootstrap: MaINBootstrapper.Initialize(); ASP.NET: services.AddMaIN(configuration)
         - MCP has 3 integration styles: direct prompt, agent pipeline step, RAG knowledge source
 
-        TOOL ECONOMY: You have 10 tool slots. list_docs (1) → read app-template doc + maybe 1 more (2) → show_file × N files (N) → propose_artifact_generation (1) = done. Never read the same file twice.
+        TOOL ECONOMY: You have 18 tool slots. list_docs (1) → read app-template doc + maybe 1 more (2) → show_file × N files (N) → propose_artifact_generation (1) = done.
+        NEVER call read_md_file twice for the same path — its content is already in an earlier tool
+        result in this conversation, re-requesting it just wastes your tool budget and gets you closer
+        to running out before propose_artifact_generation.
 
         TOOLS — use them every time, no improvising:
         1. list_docs — discover what files exist
@@ -1315,6 +1329,18 @@ before writing any code. Do not assume console.
         solution (showing the new files per the ARTIFACTS rules) before calling
         propose_artifact_generation / generate_artifact again.
 
+        DESKTOP VISUAL QUALITY — when kind is "desktop", app-template-desktop.md's "Modern
+        visual style — gradients & glass panels" and "Common AVLN2000 / XAML compile errors"
+        sections are part of the SAME read_md_file call as the rest of the template — apply
+        both. Pick an accent palette and layout shape that fit THIS app's topic (a weather
+        app, a recipe app, a budgeting app must not all look like the same blue chat window):
+        use a gradient header/hero, "glass" Border cards, and an accent color on primary
+        buttons, and shape the main layout (dashboard grid, list+detail, single tool view —
+        not always Chat+Settings tabs) around the app's actual feature. Before calling
+        show_file on any .axaml file, check every Padding/CornerRadius/BoxShadow/Spacing
+        usage against the AVLN2000 pitfalls section — wrap panels in a Border rather than
+        setting those directly on StackPanel/Grid/WrapPanel/DockPanel.
+
         CONFIG PROMPTING — every generated app MUST let the user supply backend config (model
         path/Ollama URL for local, API keys + model names for cloud) at runtime, never hardcoded:
         - console: interactive Console.ReadLine() setup wizard (see app-template-console.md)

backend/MaIN.Docs.Api/Services/MdTools.cs

@@ -8,6 +8,7 @@ public static class MdTools
     private static string _directory = "";
     private static ILogger _logger = NullLogger.Instance;
     private static Action<string, int>? _readCapture;
+    private static HashSet<string>? _readPaths;
 
     public static void Initialize(string directory, ILogger logger)
     {
@@ -18,6 +19,10 @@ public static void Initialize(string directory, ILogger logger)
     // Invoked with (path, contentLength) so the orchestrator can fold tool-result size into the token estimate.
     public static void SetReadCapture(Action<string, int>? capture) => _readCapture = capture;
 
+    // Tracks paths already read during this turn so a repeat read_md_file call for the same
+    // file doesn't re-spend tokens/iteration budget on content the model already has.
+    public static void SetReadDedup(HashSet<string>? readPaths) => _readPaths = readPaths;
+
     public record ListDocsArgs;
     public record SearchArgs(string Query);
     public record ReadArgs(string Path);
@@ -97,6 +102,17 @@ public static async Task<object> Read(ReadArgs args)
             return new { error = $"File not found: {args.Path}" };
         }
 
+        if (_readPaths is not null && !_readPaths.Add(args.Path))
+        {
+            _logger.LogInformation("[tool:read_md_file] Skipped duplicate read of {File} — already read this turn", Path.GetFileName(args.Path));
+            return new
+            {
+                path     = args.Path,
+                fileName = Path.GetFileName(args.Path),
+                note     = "Already read earlier in this turn — its full content is in an earlier tool result above. Do not request it again."
+            };
+        }
+
         var content = await File.ReadAllTextAsync(args.Path);
         _logger.LogInformation("[tool:read_md_file] Read {Bytes} chars from {File}", content.Length, Path.GetFileName(args.Path));
         _readCapture?.Invoke(args.Path, content.Length);

backend/MaIN.Docs.Api/appsettings.json

@@ -15,7 +15,24 @@
   "Capacity": {
     "Tier1": { "TokenLimit": 150000, "CooldownMinutes": 180 },
     "Tier2": { "GeminiKey": "", "TokenLimit": 1000000, "CooldownMinutes": 120 },
-    "Tier3": { "OllamaKey": "", "OllamaKey2": "", "OllamaModel": "gemma4:31b-cloud" }
+    "Tier3": { "OllamaKey": "", "OllamaKey2": "", "OllamaModel": "gemma4:31b-cloud" },
+    "ReasoningEffort": ""
+  },
+  "Models": {
+    "Tier1": {
+      "Chatty": "gemini-3.1-flash-lite",
+      "Code": "gemini-3.5-flash",
+      "Review": "gemini-3.5-flash",
+      "Design": "gemini-3.1-pro-preview",
+      "Forge": "gemini-3.1-pro-preview"
+    },
+    "Tier2": {
+      "Chatty": "gemini-3.1-flash-lite",
+      "Code": "gemini-3.1-flash-lite",
+      "Review": "gemini-3.1-flash-lite",
+      "Design": "gemini-3.1-flash-lite",
+      "Forge": "gemini-3.1-flash-lite"
+    }
   },
   "Logging": {
     "LogLevel": {

docs-content/app-template-desktop.md

@@ -465,6 +465,107 @@ property) live in `Avalonia.Platform.Storage`. There is no standalone type
 called `FileTypeFilter` — using that name as a type causes
 `CS0246: cannot find type or namespace 'FileTypeFilter'`.
 
+## Common AVLN2000 / XAML compile errors — avoid these
+
+Avalonia's XAML compiler (AVLN2000 "Unable to resolve property X on type Y") is much
+stricter about which properties exist on which controls than WPF. These are the most
+common hallucinated combinations — check for them before calling `show_file`:
+
+- **`Padding` does NOT exist on `Panel`-derived elements** — `StackPanel`, `Grid`,
+  `WrapPanel`, `DockPanel`, `Canvas` have no `Padding` property. Only `Border`,
+  `Decorator`, and `ContentControl`-derived elements (`Button`, `TextBox`,
+  `ContentControl`, `ScrollViewer`, `TabItem`, etc.) have `Padding`.
+  - To pad the contents of a `StackPanel`/`Grid`, wrap it in `<Border Padding="20">...</Border>`,
+    or set `Margin` on the panel itself.
+- **`Spacing` only exists on `StackPanel` and `WrapPanel`** — not `Grid` or `DockPanel`.
+  Use `Margin` on individual children for spacing in those.
+- **`CornerRadius` exists on `Border` and a few controls** (`Button`, `TextBox`, etc. —
+  anything templated on a rounded `ContentPresenter`/`Border`).
+- **`BoxShadow` exists ONLY on `Border`.** It is NOT a property of `Button`, `TextBox`,
+  `Image`, or any other control — `<Button BoxShadow="...">` is an AVLN2000 error. If a
+  button (or any other control) needs a shadow, wrap it in a `<Border BoxShadow="...">`,
+  or skip the shadow on that element entirely.
+- Rule of thumb: if you're adding `Padding`, `BoxShadow`, or a `Background` for visual
+  effect to a `StackPanel`/`Grid`/`WrapPanel`/`DockPanel`/`Button`/other non-`Border`
+  control, wrap that element in a `Border` and set the property on the `Border` instead.
+  `CornerRadius` is the only one of these that's safe directly on `Button`/`TextBox`.
+
+## Modern visual style — gradients & glass panels
+
+The default `FluentTheme` on its own looks flat and generic, and reusing the exact
+layout/palette from this template for every app is why generated apps look "boring and
+all the same". Layer these simple, verified techniques on top of `FluentTheme` (don't
+replace it) and pick a palette that fits the app's actual topic — a weather app, a
+recipe app, and a budgeting app should NOT end up with the same blue/gray look.
+
+### 1. App-wide accent palette in App.axaml
+
+```xml
+<Application xmlns="https://github.com/avaloniaui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             x:Class="ChatDesktop.App">
+  <Application.Styles>
+    <FluentTheme />
+  </Application.Styles>
+  <Application.Resources>
+    <SolidColorBrush x:Key="AccentBrush">#6366F1</SolidColorBrush>
+    <LinearGradientBrush x:Key="HeroGradient" StartPoint="0%,0%" EndPoint="100%,100%">
+      <GradientStop Color="#6366F1" Offset="0" />
+      <GradientStop Color="#EC4899" Offset="1" />
+    </LinearGradientBrush>
+  </Application.Resources>
+</Application>
+```
+
+Pick 2 colors that fit the app's domain instead of always reusing indigo/pink —
+e.g. sky/cyan for weather, emerald/teal for finance or health, amber/orange for
+productivity, violet/fuchsia for creative tools.
+
+### 2. Gradient header / hero panel
+
+```xml
+<Border Background="{StaticResource HeroGradient}" CornerRadius="0,0,16,16" Padding="24,18">
+  <TextBlock Text="Aura Weather" FontSize="22" FontWeight="Bold" Foreground="White" />
+</Border>
+```
+
+### 3. "Glass" cards
+
+```xml
+<Border Background="#1AFFFFFF" CornerRadius="16" Padding="18" BoxShadow="0 4 24 0 #40000000">
+  <!-- card content -->
+</Border>
+```
+
+`#1AFFFFFF` is white at ~10% opacity (ARGB hex, alpha first) — a translucent overlay
+that reads as "glass" on both dark and light window backgrounds. Increase the alpha
+(e.g. `#33FFFFFF`) for more contrast against a busy background.
+
+### 4. Window background
+
+Give the window a deliberate base color instead of the default flat gray, so the
+gradient/glass elements have something to sit on top of:
+
+```xml
+<Window ... Background="#0F172A">
+```
+
+### 5. Accent buttons
+
+```xml
+<Button Content="Refresh" Background="{StaticResource AccentBrush}" Foreground="White"
+        CornerRadius="8" Padding="14,8" />
+```
+
+### Vary the layout too, not just the colors
+
+This template's TabControl (Chat + Settings) is the right shape when the app's core
+feature genuinely is an AI chat. If the app's main feature is something else (a
+dashboard, a list + detail view, a single-page tool), build the layout that fits that
+feature — a `Grid` dashboard of `Border` "glass" cards, a master/detail `Grid` with two
+columns, etc. — and put the MaIN.NET config (Settings) behind a small gear `Button`
+that opens a second `Window`, rather than forcing every app into the same two-tab shape.
+
 ## Customizing
 
 - **Non-chat UI**: replace the Chat `TabItem` content with whatever controls suit