docs: Fix hardcoded path and add library overview in Essentials.AI README

[PureWeen]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Summary

Two improvements to src/AI/src/Essentials.AI/README.md:

1. Remove hardcoded absolute path: Replace machine-specific path with a relative path that works in any environment
2. Add library overview: Add a short description explaining what the Essentials.AI library provides, so readers understand the purpose of the package at a glance

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 35194

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 35194"

[Copilot]

Pull request overview

Updates the Essentials.AI package README to be more user-friendly by adding an introductory overview and improving the “Generating Files” instructions to avoid machine-specific paths.

Changes:

• Added an Overview section describing the library, supported platforms, how to reference the package, and where to find a sample.
• Updated the “Generating Files” section to use a cleaner fenced bash code block and replace the previous machine-specific path prefix.

[kubaflo]

/review

[github-actions]

✅ Expert Code Review completed successfully!

[github-actions]

Expert Code Review — PR #35194

Methodology: 3 independent reviewers with adversarial consensus. Findings are included only when 2+ reviewers independently identified the same root cause.

---

Summary

The hardcoded path fix (Users/matthew/... → <repo-root>/...) and the bash syntax highlighting are solid improvements. However, the new overview section contains several claims that don't match the current codebase, which could mislead developers.

---

Findings

#	Severity	Finding	Consensus	Line(s)
1	🟡 MODERATE	Platform table marks Android/Windows as ✅ but no implementations exist for those platforms	3/3 reviewers	11–14
2	🟡 MODERATE	Overview claims IChatClient/embedding abstractions work "across all platforms" — only Apple platforms have implementations	2/3 reviewers	5
3	🟡 MODERATE	Version="*-*" is unconventional floating version; may confuse consumers or resolve to broken builds	2/3 reviewers	19
4	🟢 MINOR	Sample app uses Azure OpenAI (cloud), contradicting the "on-device AI" positioning	2/3 reviewers	26
5	🟢 MINOR	EssentialsAI-485fe build-specific hash remains in path, undermining portability goal	2/3 reviewers	43
6	🟢 MINOR	Missing trailing newline at end of file	2/3 reviewers	EOF

Discarded (single reviewer only): --sdk=iphoneos26.1 becoming stale — 1/3 reviewers, not corroborated.

---

CI & Test Coverage

This is a documentation-only change (single README.md file), so no CI build or test impact is expected. No tests are needed for this change.

---

What's Good

• ✅ Removing the hardcoded user-specific path is the right fix
• ✅ Adding bash syntax highlighting improves readability
• ✅ The overall structure (overview → platforms → install → sample → generating) is well-organized
• ✅ The experimental/preview disclaimer is a good addition

Generated by Expert Code Review for issue #35194 · ● 8.1M

[kubaflo]

Thanks for the reviews! Pushed 2814a9a addressing the actionable feedback:

Applied:

• Platform table accuracy (Copilot #3153937154, github-actions #3156558974, #3156558986): Marked Android/Windows as 🚧 Planned (no built-in provider yet), since the only shipped IChatClient/IEmbeddingGenerator implementations live under Platform/MaciOS/ and the Android/Windows PublicAPI files are empty. Also softened the "across all platforms" claim in the overview paragraph.
• macOS vs Mac Catalyst (Copilot #3153937236): Split into separate rows for clarity.
• Version="*-*" (Copilot #3153937219, github-actions #3156558990): Replaced with a concrete 10.0.0-preview.1 example and added a CPM note.
• Sharpie command path (Copilot #3153937192, github-actions #3156558983): Removed the <repo-root> placeholder (now repo-root-relative) and replaced the build-specific EssentialsAI-485fe hash with EssentialsAI-XXXXX plus an explanatory comment.
• Sample is cloud, not on-device (github-actions #3156558979): Added a clarifying note that the sample requires OpenAI / Azure OpenAI credentials and does not exercise the on-device Apple Intelligence client.

No suggestions were skipped.