Add reusable AI guidance and React package catalog

docs/instructions/INDEX.md

@@ -0,0 +1,16 @@
+# Shared Instructions
+
+This folder contains stable conventions and guidance that help people navigate the reusable skill library. Repository-specific requirements remain in each repository's `AGENTS.md`; workflow procedures belong in `.agents/skills/`.
+
+## Instruction Groups
+
+- [`file-editing-conventions.md`](file-editing-conventions.md) — shared source section comments, Markdown table styling, and line endings.
+- [`development-conventions.md`](development-conventions.md) — cross-repository change boundaries.
+- [`skill-lifecycle.md`](skill-lifecycle.md) — when to use, recommend, add, or update a skill and how to keep instructions maintainable.
+
+## Related Indexes
+
+- [`../skills/INDEX.md`](../skills/INDEX.md) — available Common skills.
+- `../../AGENTS.md` — Common repository instructions.
+
+Read only the guidance relevant to the current task. Do not turn this index into a requirement to load every document before every change.

docs/instructions/development-conventions.md

@@ -0,0 +1,9 @@
+# Shared Development Conventions
+
+Use [`file-editing-conventions.md`](file-editing-conventions.md) for source section comments, Markdown table styling, and line endings.
+
+## Cross-Repository Boundaries
+
+Common, BusinessMgr, Sandtrap, and Sandalwood are separate Git workspaces. Check and report each affected repository independently. Preserve sibling project-reference layout. Keep shared findings in the Common or `SacsMobileMaui` trackers and link to them from consumer trackers instead of duplicating the analysis.
+
+The repository-owned `AGENTS.md` is authoritative for its workspace. The parent `VS2022/AGENTS.md` is an informational map only.

docs/instructions/file-editing-conventions.md

@@ -0,0 +1,38 @@
+# File Editing Conventions
+
+This document collects shared conventions that apply while editing source and documentation files. Each repository's `AGENTS.md` keeps a short, actionable summary; this file holds the full rules. Repository-specific instructions and `.gitattributes` remain authoritative for their own scope.
+
+## Code Section Comments
+
+For code files that support `//` comments, use meaningful section delimiters in the form `// --- Caption ---`, where the caption describes the code that follows. Examples include `Data Members`, `Construction`, `Properties`, `Test Support`, and `Definitions` for declarations. Reserve `Utilities` for relatively simple internal helpers; use a more specific caption for complex or domain-significant behavior. A delimiter may have explanatory comments when useful.
+
+Separate the complete comment block from surrounding code with blank lines, except directly inside opening or closing braces. Finish the file's main outer class or type with `// --- The End ---` immediately before its closing brace. Leave nested or internal types comment-free unless they are complex and at least 32 lines long; `// --- The End ---` is not required for nested types.
+
+Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file. Small, isolated changes do not require unrelated wholesale reformatting, and section delimiters should only mark distinct sections that improve readability.
+
+## Markdown Tables
+
+Every new Markdown document that contains a table must include this document-level style near the top so table headers and cells align to the top:
+
+```html
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+```
+
+Preserve the style in existing Markdown documents that contain tables. Add it when a substantive edit introduces a table into a document that does not already have it.
+
+## Formatting and Import Cleanup
+
+Follow the repository's `.editorconfig`, solution settings, and established Visual Studio conventions where available. Use Visual Studio's formatter or the repository's approved equivalent on the changed selection or file when practical. Avoid broad formatting changes to unrelated code, and do not reformat generated, vendored, minified, or otherwise excluded files.
+
+Remove `using` directives, imports, includes, or equivalent declarations only when they are demonstrably unnecessary. Consider language and build semantics: imports can run module initialization, load CSS or polyfills, register components, provide extension methods, or affect generated or conditional code. In JavaScript and React, preserve intentional bare side-effect imports such as CSS, polyfills, and setup modules. If an import exists only for tests, put it in test code rather than leaving a production placeholder for hypothetical future use. Keep a non-obvious intentional import only with a short comment or other clear explanation.
+
+After cleanup, use the applicable formatter or analyzer to confirm the result where practical, and run the validation required by the affected repository and change.
+
+## Line Endings
+
+Follow the repository's `.gitattributes` as the authority for working-tree line endings. For file types without an explicit ending policy, preserve the file's existing convention and match nearby files; do not introduce mixed endings or normalize unrelated files. Whenever a file is created or edited, ensure that file has its required line endings before validation and handoff.

docs/instructions/skill-lifecycle.md

@@ -0,0 +1,21 @@
+# Skill Lifecycle and Selection
+
+## When to Use a Skill
+
+Use a skill when its `description` matches the task and it provides a repeatable workflow, validation sequence, or domain context. Repository `AGENTS.md` files should name skills conditionally for work that needs them. Do not require unrelated skills or load every reference by default.
+
+## When to Recommend a Skill
+
+Recommend adding or updating reusable guidance when a task or review reveals a recurring multi-step procedure, repeated agent/user friction, a stable validation sequence, or a lasting policy gap. Prefer a focused skill over a broad catch-all. Keep always-applicable policy in the owning `AGENTS.md`; keep stable explanatory material in `docs/instructions/`; keep task workflows in a skill.
+
+## When to Raise It in a Conversation
+
+Check for a worthwhile library improvement at natural handoff points: when requested work is complete, a change is ready for PR review, or a PR review/merge discussion is wrapping up. Raise it briefly in the completion summary or handoff, with the proposed file and reason. Do not interrupt implementation for a speculative candidate, and do not suggest an update for a one-off fix or routine minor change. If the improvement is clearly in scope, make it and summarize it; otherwise recommend it for a follow-up.
+
+The goal is a useful, low-noise library, not a checklist item in every conversation. A high-impact policy gap can justify one recommendation even before a pattern repeats; ordinary workflow skills should be based on demonstrated reuse.
+
+## When to Add or Update a Skill
+
+Create a repo-local directory at `.agents/skills/<skill-name>/` with a `SKILL.md` containing front matter `name` and a concise `description` that says both what the workflow does and when it applies. Keep the main workflow short. Put optional supporting material in `references/`, executable helpers in `scripts/`, and reusable examples/templates in `assets/`.
+
+Update a skill when its selection conditions, required steps, validation commands, or referenced policy change. Check all links and ensure the skill does not duplicate or contradict `AGENTS.md` or an owned design record. Record significant library changes in the Common topic tracker and index.