From 72e0e47cd3988608007e1c4c7cd05551f92527e8 Mon Sep 17 00:00:00 2001
From: Codex CLI <codex@example.com>
Date: Fri, 29 Aug 2025 01:11:15 -0500
Subject: [PATCH] docs: add AGENTS.md repository guidelines and official color
 scheme

---
 AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b4595cf
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Modules
+- `src/AdvancedCalculator`: Shared UI + logic (Avalonia, ViewModels, Services, Models, Converters, Styles, Views, Assets).
+- `src/AdvancedCalculator.Desktop`: Desktop entry point (`net8.0`).
+- `src/AdvancedCalculator.Browser`: WebAssembly host (`net8.0-browser`, `wwwroot` for static assets).
+- `src/AdvancedCalculator.Android`: Android host (`net8.0-android`, `Resources`, `AndroidManifest.xml`).
+- `src/AdvancedCalculator.sln`: Solution root; `src/Directory.Build.props` centralizes common settings (nullable, Avalonia version).
+
+## Build, Run, and Development
+- Restore + build all: `dotnet build src/AdvancedCalculator.sln -c Debug`
+- Run Desktop: `dotnet run --project src/AdvancedCalculator.Desktop -c Debug`
+- Run Browser: `dotnet run --project src/AdvancedCalculator.Browser -c Debug` (open the printed local URL)
+- Build Android: `dotnet build src/AdvancedCalculator.Android -c Debug` (install APK via `adb install` from `bin/Debug/net8.0-android/`)
+- Format code: `dotnet format` (run at repo root)
+
+## Coding Style & Naming
+- C# 8+/latest, nullable enabled; 4‑space indentation, no tabs.
+- Names: PascalCase for types/properties; camelCase for locals/parameters; private fields `_camelCase`.
+- Use `var` for obvious types; prefer expression-bodied members when clear.
+- XAML: keep styles in `Styles/*.axaml`; avoid inline styling; prefer bindings and converters in `Converters/*`.
+
+## Color Scheme (Official)
+- `--c-primary-1`: `#5AC3D6`; `--c-primary-2`: `#223544`; `--c-primary-3`: `#4E6D84`.
+- `--c-emph-1`: `#F5A623`; `--c-emph-2`: `#D94E87`; `--c-emph-3`: `#49C46D`.
+- `--bg`: `var(--c-primary-3)`; `--surface`: `var(--c-primary-2)`; `--text`: `#EAF2F7`.
+- `--muted`: `rgba(255,255,255,0.75)`; `--border`: `rgba(255,255,255,0.18)`.
+- `--input-bg`: `rgba(255,255,255,0.06)`; `--input-border`: `rgba(255,255,255,0.22)`.
+- `--link`: `var(--c-primary-1)`; `--focus`: `var(--c-primary-1)`.
+- Avalonia mapping: define colors/brushes in `Styles/Colors.axaml` (e.g., `CPrimary1/2/3`, `CEmph1/2/3`; `ThemeAccentBrush` from primary‑1; background/surfaces from `--bg/--surface`; text from `--text`). Keep all UI colors derived from these tokens.
+
+## Testing Guidelines
+- No test projects yet. If adding tests, create `tests/AdvancedCalculator.Tests` (xUnit or NUnit), name files `*.Tests.cs`, and target `net8.0`.
+- Run tests with `dotnet test` at repo root or solution level.
+- Aim for coverage of `Services` and view‑model logic; UI/XAML can be validated via snapshot or behavior tests.
+
+## Commit & Pull Requests
+- Messages: imperative mood, concise subject; optionally prefix type (e.g., `feat:`, `fix:`, `theme:`) as seen in history.
+- Include a brief body for non‑trivial changes with bullet points.
+- PRs: link related issues, describe scope and platform(s) affected (Desktop/Browser/Android), include screenshots/GIFs for UI changes, and note manual test steps.
+- Keep changes scoped; avoid unrelated refactors.
+
+## Configuration Tips
+- Shared properties live in `src/Directory.Build.props`; prefer updating versions/nullable here, not per project.
+- Browser host static assets are under `src/AdvancedCalculator.Browser/wwwroot`.
+- Android package id is set in `AdvancedCalculator.Android.csproj` (`ApplicationId`). Update icons/splash in `Resources`.