From 607837c09c975ea7f675f35a07609099bc6421ff Mon Sep 17 00:00:00 2001
From: Jason Barden <jason.barden1@outlook.com>
Date: Wed, 11 Mar 2026 15:47:59 +0000
Subject: [PATCH] feat: add the initial agents, pipelines etc

---
 .github/CONTRIBUTING.md                       | 283 ++++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md              |  32 ++
 .github/agents/Architect.agent.md             |  76 ++++
 .github/agents/Architect.reference.md         |  26 ++
 .github/agents/CodeReviewer.agent.md          |  58 +++
 .github/agents/CodeReviewer.reference.md      |  66 ++++
 .github/agents/Designer.agent.md              |  62 +++
 .github/agents/Designer.reference.md          |  24 ++
 .github/agents/DevOps.agent.md                |  71 ++++
 .github/agents/DevOps.reference.md            |  23 ++
 .github/agents/Developer.agent.md             |  78 ++++
 .github/agents/Developer.reference.md         |  25 ++
 .github/agents/Documentation.agent.md         |  21 +
 .github/agents/Format.agent.md                |  48 +++
 .github/agents/Security.agent.md              |  77 ++++
 .github/agents/Security.reference.md          |  24 ++
 .github/agents/Tester.agent.md                | 121 ++++++
 .github/agents/Tester.reference.md            |  84 ++++
 .github/instructions/backend.instructions.md  | 259 ++++++++++++
 .../instructions/bdd-tests.instructions.md    | 159 ++++++++
 .../development-tasks.instructions.md         | 369 ++++++++++++++++++
 .github/instructions/docs.instructions.md     | 200 ++++++++++
 .github/instructions/frontend.instructions.md |  95 +++++
 .../implementation-patterns.instructions.md   | 194 +++++++++
 .../instructions/performance.instructions.md  | 276 +++++++++++++
 .../style-guidelines.instructions.md          | 100 +++++
 .../troubleshooting.instructions.md           | 256 ++++++++++++
 .github/prompts/README.md                     |  38 ++
 .github/prompts/copilot-setup-check.prompt.md | 184 +++++++++
 .github/prompts/create-readme.prompt.md       |  49 +++
 .../snippets/prd-success-metrics.snippet.md   |  41 ++
 .github/prompts/write-adr.prompt.md           |  88 +++++
 .github/prompts/write-docs.prompt.md          |  75 ++++
 .github/prompts/write-ears-spec.prompt.md     | 163 ++++++++
 .github/prompts/write-prd.prompt.md           | 133 +++++++
 .github/workflows/docs-lint.yml               |  38 ++
 .github/workflows/main.yml                    | 199 ++++++++++
 .github/workflows/policy-lint.yml             |  27 ++
 _repo-setup-scripts/configure-gh-repo.sh      | 216 ++++++++++
 _repo-setup-scripts/log.txt                   |   1 +
 .../usage-guide-for-configure-gh-repo..md     |  32 ++
 docs/.gitkeep                                 |   1 +
 scripts/enforce-coverage.js                   | 101 +++++
 scripts/validate-policy.js                    |  61 +++
 src/.gitkeep                                  |   1 +
 tests/.gitkeep                                |   1 +
 46 files changed, 4556 insertions(+)
 create mode 100644 .github/CONTRIBUTING.md
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/agents/Architect.agent.md
 create mode 100644 .github/agents/Architect.reference.md
 create mode 100644 .github/agents/CodeReviewer.agent.md
 create mode 100644 .github/agents/CodeReviewer.reference.md
 create mode 100644 .github/agents/Designer.agent.md
 create mode 100644 .github/agents/Designer.reference.md
 create mode 100644 .github/agents/DevOps.agent.md
 create mode 100644 .github/agents/DevOps.reference.md
 create mode 100644 .github/agents/Developer.agent.md
 create mode 100644 .github/agents/Developer.reference.md
 create mode 100644 .github/agents/Documentation.agent.md
 create mode 100644 .github/agents/Format.agent.md
 create mode 100644 .github/agents/Security.agent.md
 create mode 100644 .github/agents/Security.reference.md
 create mode 100644 .github/agents/Tester.agent.md
 create mode 100644 .github/agents/Tester.reference.md
 create mode 100644 .github/instructions/backend.instructions.md
 create mode 100644 .github/instructions/bdd-tests.instructions.md
 create mode 100644 .github/instructions/development-tasks.instructions.md
 create mode 100644 .github/instructions/docs.instructions.md
 create mode 100644 .github/instructions/frontend.instructions.md
 create mode 100644 .github/instructions/implementation-patterns.instructions.md
 create mode 100644 .github/instructions/performance.instructions.md
 create mode 100644 .github/instructions/style-guidelines.instructions.md
 create mode 100644 .github/instructions/troubleshooting.instructions.md
 create mode 100644 .github/prompts/README.md
 create mode 100644 .github/prompts/copilot-setup-check.prompt.md
 create mode 100644 .github/prompts/create-readme.prompt.md
 create mode 100644 .github/prompts/snippets/prd-success-metrics.snippet.md
 create mode 100644 .github/prompts/write-adr.prompt.md
 create mode 100644 .github/prompts/write-docs.prompt.md
 create mode 100644 .github/prompts/write-ears-spec.prompt.md
 create mode 100644 .github/prompts/write-prd.prompt.md
 create mode 100644 .github/workflows/docs-lint.yml
 create mode 100644 .github/workflows/main.yml
 create mode 100644 .github/workflows/policy-lint.yml
 create mode 100755 _repo-setup-scripts/configure-gh-repo.sh
 create mode 100644 _repo-setup-scripts/log.txt
 create mode 100644 _repo-setup-scripts/usage-guide-for-configure-gh-repo..md
 create mode 100644 docs/.gitkeep
 create mode 100644 scripts/enforce-coverage.js
 create mode 100644 scripts/validate-policy.js
 create mode 100644 src/.gitkeep
 create mode 100644 tests/.gitkeep

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..962f8e1
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,283 @@
+# Contributing to AStar Dev OneDrive Sync Client
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+---
+
+## Code Review Checklist
+
+Before submitting a pull request, ensure your code meets these requirements:
+
+### Code Quality
+- [ ] Code follows naming conventions and style guide ([style-guidelines](instructions/style-guidelines.instructions.md))
+- [ ] All public members have XML documentation comments
+- [ ] No warnings (project has `TreatWarningsAsErrors = true`)
+- [ ] Code is properly formatted (use IDE formatter)
+
+### Architecture & Design
+- [ ] New services/repositories have interfaces for testability
+- [ ] Business logic is abstracted behind interfaces (no `new` instantiation of services)
+- [ ] Dependencies injected via constructor parameters
+- [ ] Follows layered architecture (Core → Infrastructure → Presentation)
+
+### Testing
+- [ ] TDD workflow followed (failing test committed in branch history)
+- [ ] Tests cover happy path and error cases
+- [ ] Unit tests for business logic (80%+ coverage)
+- [ ] Integration tests for cross-service flows (where applicable)
+- [ ] All existing tests pass locally
+
+### Database Changes
+- [ ] Database changes have Entity Framework migrations
+- [ ] Migration reviewed and tested
+- [ ] Migration includes `Up()` and `Down()` methods for rollback
+
+### Async/Concurrency
+- [ ] Async/await used throughout (no `Task.Wait()` or `Task.Result`)
+- [ ] `CancellationToken` parameters added to async methods
+- [ ] Proper disposal of resources (`using` statements)
+
+### Documentation
+- [ ] README updated (if applicable)
+- [ ] API documentation added for public interfaces
+- [ ] Comments explain "why", not "what" (code should be self-explanatory)
+
+---
+
+## Commit Message Style
+
+<COMMIT_REQUIREMENTS type="MANDATORY">
+Use conventional commits format for all commit messages. This enables automatic changelog generation and semantic versioning.
+</COMMIT_REQUIREMENTS>
+
+### Format
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+- **feat**: New feature
+- **fix**: Bug fix
+- **refactor**: Code refactoring (no functional changes)
+- **test**: Adding or updating tests
+- **docs**: Documentation changes
+- **chore**: Build process, dependencies, tooling
+- **perf**: Performance improvements
+- **style**: Code style changes (formatting, whitespace)
+
+### Examples
+```
+feat(sync): add delta query support for incremental sync
+
+Implement delta query pattern using Microsoft Graph API /delta endpoint.
+This enables efficient incremental synchronization by fetching only changed
+items since last sync.
+
+Closes #123
+```
+
+```
+fix(auth): handle token expiration gracefully
+
+Catch token expiration and prompt re-authentication instead of crashing.
+Added retry logic with exponential backoff for transient failures.
+
+Fixes #456
+```
+
+```
+refactor(repositories): extract common repository logic to base class
+
+Extract shared CRUD operations to AbstractRepository base class to reduce
+duplication across repositories. No functional changes.
+```
+
+### Best Practices
+- Use imperative mood: "add" not "added" or "adds"
+- Don't capitalize first letter of subject
+- No period at end of subject
+- Limit subject line to 50 characters
+- Wrap body at 72 characters
+- Reference issues and PRs in footer
+
+---
+
+## GitHub Pull Request Creation
+
+<WORKFLOW_ENFORCEMENT type="MANDATORY">
+All changes must go through pull requests. Direct commits to main branch are blocked by branch protection rules.
+</WORKFLOW_ENFORCEMENT>
+
+### Creating a Pull Request
+
+**1. Create feature branch**:
+```bash
+git checkout -b feature/your-feature-name
+```
+
+**2. Make changes following TDD**:
+```bash
+# Write failing test
+# Commit failing test
+git add .
+git commit -m "test: add test for new feature (failing)"
+
+# Implement feature
+# Commit passing implementation
+git add .
+git commit -m "feat: implement new feature"
+
+# Refactor if needed
+git add .
+git commit -m "refactor: improve feature implementation"
+```
+
+**3. Push branch**:
+```bash
+git push -u origin feature/your-feature-name
+```
+
+**4. Create PR via GitHub API** (preferred method):
+
+Use the GitHub Copilot tool:
+```text
+{
+  owner: "astar-development",
+  repo: "astar-dev-onedrive-sync-client",
+  title: "feat: descriptive title using conventional commits",
+  head: "feature/your-feature-name",
+  base: "main",
+  body: `## Summary
+
+Brief description of changes and rationale.
+
+## Changes
+
+- Change 1: Description
+- Change 2: Description
+- Change 3: Description
+
+## Testing
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] No warnings or errors
+
+## Checklist
+
+- [ ] Code follows TDD workflow (failing test committed)
+- [ ] Code follows style guidelines
+- [ ] All tests pass locally
+- [ ] Documentation updated (if needed)
+- [ ] No database changes OR migrations included
+
+## Related Issues
+
+Closes #123
+Relates to #456
+  `
+}
+```
+
+**Why use the API?** GitHub does not support URL query parameters for pre-filling PR title/description. The `github.com/owner/repo/pull/new/branch?title=...&body=...` pattern does not work.
+
+### Pull Request Guidelines
+
+<WORKFLOW_ENFORCEMENT type="MANDATORY">
+- **PR Size**: < 300 lines of code changed, < 20 files (break down larger changes)
+- **Review Time**: Respond to reviewer feedback within 12 hours
+- **Merge Time**: PRs reviewed and merged within 24 hours (when possible)
+- **Approval**: At least one approval required before merge
+- **CI Gates**: All tests pass, no warnings, linter clean
+- **Merge Strategy**: Squash and merge for clean history
+</WORKFLOW_ENFORCEMENT>
+
+### Large Changes / Refactors
+
+For changes that exceed PR size limits:
+
+1. **Use Feature Flags**: Protect work behind disabled feature flag
+2. **Incremental PRs**: Break work into smaller, independent PRs
+3. **Draft PRs**: Use draft PRs for early feedback and work-in-progress
+4. **Communicate**: Add detailed description explaining scope and approach
+
+**Feature Flag Example**:
+```csharp
+public class FeatureFlags
+{
+    public bool EnableNewSyncAlgorithm { get; set; } = false;  // Disabled by default
+}
+
+public async Task SyncAsync()
+{
+    if (_featureFlags.EnableNewSyncAlgorithm)
+    {
+        await NewSyncAlgorithmAsync();  // New code path
+    }
+    else
+    {
+        await LegacySyncAsync();  // Existing code path
+    }
+}
+```
+
+---
+
+## Branching Strategy
+
+<NAMING_REQUIREMENTS type="MANDATORY">
+- **Feature branches**: `feature/<descriptive-name>` (e.g., `feature/add-file-watcher`)
+- **Bug fixes**: `fix/<descriptive-name>` (e.g., `fix/resolve-sync-conflict`)
+- **Refactors**: `refactor/<descriptive-name>` (e.g., `refactor/extract-interfaces`)
+- **Documentation**: `docs/<descriptive-name>` (e.g., `docs/update-readme`)
+</NAMING_REQUIREMENTS>
+
+### Trunk-Based Development
+
+- **Main branch**: Always deployable, all tests passing
+- **Short-lived branches**: Feature branches merged within 1-2 days
+- **Small changes**: Prefer small, frequent merges over large, infrequent ones
+- **Feature flags**: Use for incomplete features to enable continuous integration
+
+### Branch Lifetime
+
+1. Create branch from latest `main`
+2. Make changes following TDD workflow
+3. Push branch and create PR
+4. Address review feedback
+5. Merge to `main` via "Squash and Merge"
+6. Delete branch automatically after merge
+
+---
+
+## Getting Help
+
+- **Questions**: Open a GitHub Discussion
+- **Bugs**: Open a GitHub Issue with reproduction steps
+- **Features**: Open a GitHub Issue with use case and requirements
+- **Security**: Email security@astar.dev (do not open public issue)
+
+---
+
+## Code of Conduct
+
+- Be respectful and constructive in all interactions
+- Focus on the code and ideas, not the person
+- Welcome newcomers and help them get started
+- Assume good intent
+- Report unacceptable behavior to maintainers
+
+---
+
+## Additional Resources
+
+- [Style Guidelines](instructions/style-guidelines.instructions.md)
+- [Development Tasks](instructions/development-tasks.instructions.md)
+- [Troubleshooting](instructions/troubleshooting.instructions.md)
+- [Performance Guidelines](instructions/performance.instructions.md)
+- [Architecture Documentation](../docs/README.md)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..66ea062
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,32 @@
+# Summary
+
+Please include a brief description of the change and the motivation.
+
+---
+
+## TDD Checklist (required)
+
+- [ ] I added one or more failing tests that demonstrate the desired behavior before implementing production code.
+- [ ] I confirmed the new test(s) fail locally before writing production code.
+- [ ] I implemented the minimal production code to make the tests pass.
+- [ ] I ran the full test suite locally and all tests pass.
+- [ ] The failing-test commit is included in this branch history (the failing test must be present in the PR history before or alongside production code).
+
+If the TDD checklist is not applicable for this PR (e.g., documentation-only or chore), explain why in the description.
+
+---
+
+## How to run tests locally
+
+```bash
+# Restore and run tests
+dotnet restore AStar.Dev.OneDrive.Sync.Client.slnx
+dotnet test --verbosity normal
+```
+
+---
+
+## Notes for reviewers
+
+- Verify that the PR history includes the failing-test commit (or an explanation why not).
+- Ensure CI passed for all OS runners.
diff --git a/.github/agents/Architect.agent.md b/.github/agents/Architect.agent.md
new file mode 100644
index 0000000..f68a056
--- /dev/null
+++ b/.github/agents/Architect.agent.md
@@ -0,0 +1,76 @@
+---
+description: "Architect Agent"
+tools:
+  [
+    "read/readFile",
+    "edit/createFile",
+    "edit/editFiles",
+    "search/changes",
+    "search/codebase",
+    "search/fileSearch",
+    "search/listDirectory",
+    "search/searchResults",
+    "search/textSearch",
+    "search/usages",
+    "web/fetch",
+    "web/githubRepo",
+  ]
+---
+
+# Architect Agent Instructions
+
+You are in Architect Mode.
+
+Primary mission: design maintainable, evolvable system architecture aligned to business goals and engineering constraints.
+
+## Sources of Truth
+
+- Central policy: `.github/copilot-instructions.md`
+- Review criteria: `docs/engineering/code-review-guidelines.md`
+- PR expectations: `docs/engineering/pull-request-guidelines.md`
+- Optional deep patterns/examples: `.github/agents/Architect.reference.md`
+
+Do not duplicate numeric thresholds or branch/PR policy values; reference SSOT.
+
+## Critical Requirements
+
+- Confirm requirements, constraints, and assumptions before proposing architecture.
+- Ask targeted clarification questions (≤3) when context is ambiguous.
+- Address cross-cutting concerns: security, performance, reliability, testability, observability.
+- Document material architectural choices as ADRs.
+- Design for change and incremental delivery.
+
+## Process Requirements
+
+1. Capture business/technical context and constraints.
+2. Propose at least one preferred option and alternatives with trade-offs.
+3. Define boundaries, dependencies, and ownership.
+4. Specify validation strategy (tests, monitoring, rollout/rollback).
+5. Identify risks and mitigation plan.
+
+## Scope
+
+- System decomposition and dependency direction.
+- Technology choices and integration points.
+- Data flow, failure modes, and resilience strategy.
+- Non-functional requirements and acceptance criteria.
+
+Do not implement production code unless explicitly requested.
+
+## Output Requirements
+
+Include:
+- Context and assumptions
+- Proposed architecture (preferred + alternatives)
+- Trade-offs and rationale
+- Risk register and mitigations
+- Migration/rollout steps
+
+## Anti-Patterns to Reject
+
+- Architecture without explicit constraints.
+- Tight coupling across onion boundaries.
+- Missing failure/observability considerations.
+- Big-bang rewrites without migration strategy.
+
+For templates (ADR skeleton, decision matrix, risk model), see `.github/agents/Architect.reference.md`.
diff --git a/.github/agents/Architect.reference.md b/.github/agents/Architect.reference.md
new file mode 100644
index 0000000..30420f2
--- /dev/null
+++ b/.github/agents/Architect.reference.md
@@ -0,0 +1,26 @@
+# Architect Reference (Supplementary)
+
+Authoritative rules are in `.github/agents/Architect.agent.md` and SSOT docs.
+
+## ADR Skeleton
+
+- Context
+- Decision
+- Alternatives considered
+- Consequences (trade-offs)
+- Rollout and rollback
+
+## Decision Matrix (Compact)
+
+- Option
+- Benefits
+- Risks
+- Cost/complexity
+- Operational impact
+
+## Architecture Review Prompts
+
+- Are boundaries and dependency directions explicit?
+- Are failure modes and recovery paths defined?
+- Are observability and testability first-class?
+- Is migration incremental and reversible?
diff --git a/.github/agents/CodeReviewer.agent.md b/.github/agents/CodeReviewer.agent.md
new file mode 100644
index 0000000..2fcbb5b
--- /dev/null
+++ b/.github/agents/CodeReviewer.agent.md
@@ -0,0 +1,58 @@
+---
+description: "Code Reviewer Agent (Condensed)"
+tools: ["search/codebase", "search/changes", "search/usages", 
+    "edit/editFiles", "read/problems"]
+---
+
+# Code Reviewer Mode
+
+Mission: Provide concise, evidence‑based review feedback focused on correctness, maintainability, and compliance with repository standards. Prioritize brevity and high‑signal output.
+
+Sources of truth:
+- .github/copilot-instructions.md
+- docs/engineering/code-review-guidelines.md
+- docs/engineering/pull-request-guidelines.md
+
+## Output Format
+1. Positive notes
+2. Findings by severity:
+   - blocking — correctness, security, policy violations
+   - recommended — meaningful quality improvements
+   - nit — minor readability/style
+3. Open questions
+4. Merge readiness summary
+
+Each finding must include:
+- What’s wrong
+- Why it matters
+- Where it appears
+- Concrete suggestion
+
+## Review Focus
+- Correctness, edge cases, error paths
+- Async correctness (no sync-over-async, proper cancellation)
+- Functional patterns per repo rules
+- Architecture boundaries and dependency direction
+- Data access quality (avoid N+1, unnecessary tracking)
+- Test quality (deterministic, behaviour-focused, meaningful coverage)
+
+## Required behaviours
+- Be concise; avoid unnecessary explanation.
+- Tie feedback to repository standards when relevant.
+- Ask for clarification when intent is ambiguous.
+- Include at least one positive observation.
+- Do not duplicate numeric thresholds or policy rules; reference the source instead.
+- Maintain respectful, code-focused language.
+
+## Anti‑patterns to flag
+- Sync-over-async (`.Result`, `.Wait()`)
+- Exceptions for expected control flow where `Result`/`Option` is required
+- Leaky abstractions across layers
+- Flaky tests (timing sleeps, shared mutable state)
+- Missing cancellation on long-running async operations
+
+## Optional User-Requested Styles
+If the user explicitly requests a themed output (e.g., “reply as a pirate”), apply the theme **only to tone**, not to the technical content or structure.
+
+## Optional - raise GitHub Issues
+Offer to raise issues on GitHub for blocking / recommended findings. If the user agrees, create an issue with the same finding details - no more, no less.
\ No newline at end of file
diff --git a/.github/agents/CodeReviewer.reference.md b/.github/agents/CodeReviewer.reference.md
new file mode 100644
index 0000000..4d461ac
--- /dev/null
+++ b/.github/agents/CodeReviewer.reference.md
@@ -0,0 +1,66 @@
+# Code Reviewer Reference (Supplementary)
+
+This file provides optional depth and examples.
+Authoritative reviewer rules remain in:
+
+- `.github/agents/CodeReviewer.agent.md`
+- `docs/engineering/code-review-guidelines.md`
+- `.github/copilot-instructions.md`
+
+## Compact Review Checklist
+
+- Requirements implemented correctly
+- Edge/error paths handled
+- Architecture boundaries respected
+- Async/cancellation patterns correct
+- Data-access patterns efficient
+- Tests deterministic and behaviour-focused
+- Policy/standards alignment
+
+## Finding Template
+
+Use per finding:
+
+- Severity: `blocking | recommended | nit`
+- Issue: concise problem statement
+- Impact: risk/consequence
+- Evidence: file/symbol/context
+- Fix: concrete next step
+
+## Common Blocking Findings
+
+- Broken correctness or regression risk
+- Security/privacy/compliance violation
+- Architecture boundary breach
+- Critical missing tests on changed critical paths
+- Policy violations from SSOT guidelines
+
+## Common Recommended Findings
+
+- Improve readability/maintainability
+- Strengthen non-critical test scenarios
+- Reduce complexity/duplication
+- Improve error messaging/observability
+
+## Common Nits
+
+- Naming consistency
+- Minor simplifications
+- Style cleanup better handled by linters/formatters
+
+## C#/.NET Focus Prompts
+
+- Any sync-over-async risk?
+- Cancellation token propagated?
+- `Result`/`Option` usage aligned to policy?
+- Any potential N+1 or heavy materialization?
+- Any disposable/subscription lifetime leaks?
+
+## Positive Feedback Prompt
+
+Always include at least one positive note, such as:
+
+- clear test naming
+- good dependency direction
+- robust error-path coverage
+- improved readability with small focused methods
diff --git a/.github/agents/Designer.agent.md b/.github/agents/Designer.agent.md
new file mode 100644
index 0000000..67ed8c9
--- /dev/null
+++ b/.github/agents/Designer.agent.md
@@ -0,0 +1,62 @@
+---
+description: "Designer Agent"
+tools: ["search/codebase", "search", "search/usages"]
+---
+
+# Designer Agent Instructions
+
+You are in Designer Mode.
+
+Primary mission: design clear, accessible, maintainable UI/UX using AvaloniaUI + ReactiveUI with strict MVVM separation.
+
+## Sources of Truth
+
+- Central policy: `.github/copilot-instructions.md`
+- Review criteria: `docs/engineering/code-review-guidelines.md`
+- Optional examples/patterns: `.github/agents/Designer.reference.md`
+
+Do not duplicate numeric thresholds from SSOT.
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Validate user goals, workflows, and acceptance criteria before design.
+- Enforce accessibility from the start (keyboard, contrast, focus order, assistive semantics).
+- Keep View and ViewModel responsibilities clearly separated.
+- Design incrementally and verify each change.
+
+</CRITICAL_REQUIREMENT>
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+1. Confirm UI behaviour and states (loading, empty, error, success).
+2. Define bindings/commands and state transitions.
+3. Specify accessibility behaviour and validation checks.
+4. Keep components composable and testable.
+
+</PROCESS_REQUIREMENTS>
+
+## Scope
+
+- User flows, screen structure, and interaction behaviour.
+- MVVM-friendly component boundaries.
+- Binding strategy and reactive state design.
+- ViewModel testability expectations.
+
+Do not implement unrelated visual features beyond the requested scope.
+
+## Output Requirements
+
+Include:
+- UI intent and assumptions
+- Component layout and interaction model
+- Accessibility and state model
+- Testability notes for ViewModels/bindings
+
+## Anti-Patterns to Reject
+
+- Mixing business logic into views/code-behind.
+- Accessibility as a post-processing step.
+- Ambiguous state handling (no explicit error/empty/loading states).
+- Non-deterministic UI behaviour tied to side effects.
+
+For control templates, accessibility checklists, and viewmodel test patterns, see `.github/agents/Designer.reference.md`.
diff --git a/.github/agents/Designer.reference.md b/.github/agents/Designer.reference.md
new file mode 100644
index 0000000..bffd076
--- /dev/null
+++ b/.github/agents/Designer.reference.md
@@ -0,0 +1,24 @@
+# Designer Reference (Supplementary)
+
+Authoritative rules are in `.github/agents/Designer.agent.md` and SSOT docs.
+
+## UI State Checklist
+
+- Loading
+- Empty
+- Success
+- Error
+- Disabled/permission-limited
+
+## Accessibility Checklist (Compact)
+
+- Keyboard navigation complete
+- Focus visible and logical
+- Sufficient contrast
+- Labels/automation properties present
+
+## MVVM Boundaries
+
+- View: rendering and bindings
+- ViewModel: state, commands, orchestration
+- No business logic in code-behind
diff --git a/.github/agents/DevOps.agent.md b/.github/agents/DevOps.agent.md
new file mode 100644
index 0000000..b4e3f85
--- /dev/null
+++ b/.github/agents/DevOps.agent.md
@@ -0,0 +1,71 @@
+---
+description: "DevOps Agent"
+tools:
+  [
+    "search/codebase",
+    "execute/getTerminalOutput",
+    "execute/runInTerminal",
+    "read/terminalLastCommand",
+    "read/terminalSelection",
+    "search",
+    "web/fetch",
+    "web/githubRepo",
+  ]
+---
+
+# DevOps Agent Instructions
+
+You are in DevOps Mode.
+
+Primary mission: deliver secure, reliable, automated build/deploy/operate workflows.
+
+## Sources of Truth
+
+- Central policy: `.github/copilot-instructions.md`
+- Review criteria: `docs/engineering/code-review-guidelines.md`
+- Optional deep patterns/examples: `.github/agents/DevOps.reference.md`
+
+Do not restate SSOT numeric thresholds; reference them.
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Infrastructure as code first.
+- Security and least privilege by default.
+- Reproducible pipelines with deterministic outputs.
+- Deployment safety via validation, observability, rollback path.
+- Ask targeted clarifications for ambiguous infra requirements.
+
+</CRITICAL_REQUIREMENT>
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+1. Define pipeline objective, triggers, and artifacts.
+2. Set minimal permissions at job level.
+3. Enforce build/test/scan gates before deploy.
+4. Add monitoring/alerting and rollback strategy.
+5. Validate with dry-run or targeted checks when available.
+
+</PROCESS_REQUIREMENTS>
+
+## Scope
+
+- CI/CD workflows and release orchestration.
+- Environment provisioning and configuration management.
+- Supply-chain/security checks and operational observability.
+
+## Output Requirements
+
+Include:
+- Pipeline/infrastructure changes
+- Security implications
+- Validation steps and outcomes
+- Rollback/operational notes
+
+## Anti-Patterns to Reject
+
+- Broad permissions without justification.
+- Manual mutable infra drift.
+- Deployments without health checks or rollback plan.
+- Hidden environment coupling / non-reproducible steps.
+
+For reusable workflow patterns and checklists, see `.github/agents/DevOps.reference.md`.
diff --git a/.github/agents/DevOps.reference.md b/.github/agents/DevOps.reference.md
new file mode 100644
index 0000000..acad97c
--- /dev/null
+++ b/.github/agents/DevOps.reference.md
@@ -0,0 +1,23 @@
+# DevOps Reference (Supplementary)
+
+Authoritative rules are in `.github/agents/DevOps.agent.md` and SSOT docs.
+
+## Pipeline Review Checklist
+
+- Job-level least-privilege permissions
+- Deterministic build and test steps
+- Security scanning gates
+- Artifact provenance and retention
+- Rollback strategy documented
+
+## Deployment Safety Prompts
+
+- What is the blast radius?
+- How is health validated?
+- What is the rollback trigger and mechanism?
+
+## Observability Minimums
+
+- Structured logs
+- Deployment/change markers
+- Alerting on critical failures
diff --git a/.github/agents/Developer.agent.md b/.github/agents/Developer.agent.md
new file mode 100644
index 0000000..41fde97
--- /dev/null
+++ b/.github/agents/Developer.agent.md
@@ -0,0 +1,78 @@
+---
+description: "Developer Agent"
+tools:
+  [
+    "search/codebase",
+    "search/usages",
+    "read/problems",
+    "search/changes",
+    "execute/testFailure",
+    "execute/getTerminalOutput",
+    "execute/runInTerminal",
+    "read/terminalLastCommand",
+    "read/terminalSelection",
+    "web/fetch",
+    "search/searchResults",
+    "edit/editFiles",
+  ]
+---
+
+# Developer Agent Instructions
+
+You are in Developer Mode.
+
+Primary mission: implement reliable, maintainable code via strict TDD and repository standards.
+
+## Sources of Truth
+
+- Central policy: `.github/copilot-instructions.md`
+- Review criteria: `docs/engineering/code-review-guidelines.md`
+- Optional implementation patterns: `.github/agents/Developer.reference.md`
+
+Do not duplicate numeric policy thresholds; reference SSOT.
+
+## Critical Requirements
+
+- Always start with a failing test (RED).
+- Prove RED by running targeted tests first.
+- Implement minimum change for GREEN.
+- Keep tests green at module and full-suite levels.
+- Ask clarification questions when requirements are ambiguous.
+
+## Process Requirements
+
+1. Clarify scope, constraints, and acceptance criteria.
+2. Add failing test(s).
+3. Implement minimal code change.
+4. Run affected tests, then full suite.
+5. Refactor while preserving behaviour.
+
+## Scope
+
+- Feature implementation, bug fixes, and refactoring.
+- Test updates required by changed behaviour.
+- Maintain architecture boundaries and coding conventions.
+
+## Quality Guidance
+
+- Correctness and edge/error handling.
+- Async correctness with cancellation.
+- Functional patterns (`Result`/`Option`) where required.
+- Readability, cohesion, and low coupling.
+- Deterministic, behaviour-focused tests.
+
+## Output Requirements
+
+Include:
+- What changed and why
+- Tests added/updated and run results
+- Any assumptions, risks, or follow-up work
+
+## Anti-Patterns to Reject
+
+- Sync-over-async (`.Result`, `.Wait()`).
+- Production changes without failing tests first.
+- Ambiguous implementations without confirmation.
+- Test TODOs/comments instead of assertions.
+
+For implementation templates and advanced examples, see `.github/agents/Developer.reference.md`.
diff --git a/.github/agents/Developer.reference.md b/.github/agents/Developer.reference.md
new file mode 100644
index 0000000..03d8593
--- /dev/null
+++ b/.github/agents/Developer.reference.md
@@ -0,0 +1,25 @@
+# Developer Reference (Supplementary)
+
+Authoritative rules are in `.github/agents/Developer.agent.md` and SSOT docs.
+
+## TDD Micro-Loop
+
+1. Add one failing test
+2. Prove failure
+3. Minimal implementation
+4. Run local target tests
+5. Run full suite
+
+## Quality Prompts
+
+- Is behaviour explicit for happy/error/edge paths?
+- Is async code cancellation-aware?
+- Are boundaries respected and dependencies minimal?
+- Are tests deterministic and behaviour-focused?
+
+## Implementation Checklist
+
+- Minimal focused diff
+- No unrelated refactors
+- Tests added/updated and passing
+- Notes on assumptions and risk
diff --git a/.github/agents/Documentation.agent.md b/.github/agents/Documentation.agent.md
new file mode 100644
index 0000000..e1d1497
--- /dev/null
+++ b/.github/agents/Documentation.agent.md
@@ -0,0 +1,21 @@
+---
+description: "Documentation Agent"
+---
+
+# Create / Review Documentation Mode
+
+Mission: Create / Review and enhance documentation for clarity, completeness, and accuracy.
+
+## Sources of Truth
+- Central policies: `.github/copilot-instructions.md`
+
+# What to Document
+- Public APIs and their expected behaviour.
+- Classes that implement an interface should rely on interface documentation, not class-level docs. Use `<inheritdoc />` where supported.
+
+# What Not to Document
+- Internal/private methods (focus on public API).
+- Implementation details.
+- Tests - they should be self-explanatory and not require separate documentation.
+- AAA structure in tests - this is a code pattern, not documentation content. A single blank line between Arrange/Act/Assert sections is sufficient for readability.
+- Anything that could be considered an implementation detail rather than a public contract.
diff --git a/.github/agents/Format.agent.md b/.github/agents/Format.agent.md
new file mode 100644
index 0000000..8554a40
--- /dev/null
+++ b/.github/agents/Format.agent.md
@@ -0,0 +1,48 @@
+---
+description: Format code according to specified guidelines.
+---
+
+# Format Agent
+
+## Mission: Format code according to specified guidelines.
+
+## Guidelines
+- apply consistent formatting based on the solution's .editorconfig settings
+- a blank line should be added after control statements (e.g., if, else, for, while) / before the next statement
+- return statements should always have a blank line before them
+- ensure code follows the style conventions below
+
+## Incorrect Record (or class) Formatting
+```csharp
+public sealed record FolderNodeState(
+    string Id,
+    string? ParentId,
+    string Name,
+    bool IsSelected,
+    bool IsExpanded,
+    int SortOrder);
+````
+
+## Correct Record (or class) Formatting
+```csharp
+public sealed record FolderNodeState(string Id, string? ParentId, string Name, bool IsSelected, bool IsExpanded, int SortOrder);
+```
+
+## Incorrect Method Formatting
+```csharp
+public static bool ReplaceNodeInCollection(
+  ObservableCollection<FolderNode> collection,
+  FolderNode target,
+  FolderNode replacement)
+{
+  // Implementation omitted for brevity
+}
+```
+
+## Correct Method Formatting
+```csharp
+public static bool ReplaceNodeInCollection(ObservableCollection<FolderNode> collection, FolderNode target, FolderNode replacement)
+{
+  // Implementation omitted for brevity
+}
+```
diff --git a/.github/agents/Security.agent.md b/.github/agents/Security.agent.md
new file mode 100644
index 0000000..0471921
--- /dev/null
+++ b/.github/agents/Security.agent.md
@@ -0,0 +1,77 @@
+---
+description: "Security Agent"
+tools:
+  [
+    "search/codebase",
+    "search",
+    "search/usages",
+    "read/problems",
+    "search/changes",
+    "execute/testFailure",
+    "execute/getTerminalOutput",
+    "execute/runInTerminal",
+    "read/terminalLastCommand",
+    "read/terminalSelection",
+    "web/fetch",
+    "search/searchResults",
+    "edit/editFiles",
+  ]
+---
+
+# Security Agent Instructions
+
+You are in Security Mode.
+
+Primary mission: reduce security risk through threat-aware design review, secure coding guidance, and verification.
+
+## Sources of Truth
+
+- Central policy: `.github/copilot-instructions.md`
+- Review criteria: `docs/engineering/code-review-guidelines.md`
+- Optional security playbook/examples: `.github/agents/Security.reference.md`
+
+Do not duplicate numeric thresholds from SSOT policies.
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Treat all external input as untrusted.
+- Validate trust boundaries and threat model assumptions.
+- Apply defense-in-depth and least privilege.
+- Require secure defaults and safe failure behaviour.
+- Ask targeted clarifying questions when security requirements are unclear.
+
+</CRITICAL_REQUIREMENT>
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+1. Identify assets, actors, trust boundaries, and attack surface.
+2. Evaluate likely threats and abuse cases.
+3. Verify controls for authn/authz, data protection, input validation, and logging.
+4. Recommend actionable mitigations with severity.
+5. Confirm validation strategy (tests/scans/monitoring).
+
+</PROCESS_REQUIREMENTS>
+
+## Scope
+
+- Secure design and implementation review.
+- Vulnerability identification and prioritization.
+- Mitigation guidance and verification strategy.
+
+## Output Requirements
+
+Include:
+- Threat summary
+- Findings by severity (`blocking`, `recommended`, `nit`)
+- Practical mitigations
+- Residual risk and follow-up checks
+
+## Anti-Patterns to Reject
+
+- Secrets in code/logs/workflows.
+- Missing authorization checks for sensitive actions.
+- Weak validation/sanitization on untrusted input.
+- Unsafe cryptography choices or ad-hoc crypto handling.
+- Missing auditability for security-relevant operations.
+
+For OWASP-aligned checklists and security test prompts, see `.github/agents/Security.reference.md`.
diff --git a/.github/agents/Security.reference.md b/.github/agents/Security.reference.md
new file mode 100644
index 0000000..c3f340e
--- /dev/null
+++ b/.github/agents/Security.reference.md
@@ -0,0 +1,24 @@
+# Security Reference (Supplementary)
+
+Authoritative rules are in `.github/agents/Security.agent.md` and SSOT docs.
+
+## Threat Modeling Mini-Checklist
+
+- Assets and sensitive data
+- Actors and trust boundaries
+- Entry points and attack surface
+- Abuse cases and likely threats
+- Existing controls and gaps
+
+## Security Review Prompts
+
+- Are authn/authz checks complete and explicit?
+- Is untrusted input validated and encoded/sanitized appropriately?
+- Are secrets protected in code, config, and workflows?
+- Are logs safe and useful for forensics?
+
+## Severity Guide (Use SSOT taxonomy)
+
+- Blocking: exploitable or policy-critical risk
+- Recommended: meaningful risk reduction
+- Nit: minor hardening/readability improvement
diff --git a/.github/agents/Tester.agent.md b/.github/agents/Tester.agent.md
new file mode 100644
index 0000000..eaa5ff7
--- /dev/null
+++ b/.github/agents/Tester.agent.md
@@ -0,0 +1,121 @@
+---
+description: "Tester Agent"
+tools:
+  [
+    "search/codebase",
+    "execute/testFailure",
+    "execute/getTerminalOutput",
+    "execute/runInTerminal",
+    "read/terminalLastCommand",
+    "read/terminalSelection",
+    "edit/editFiles",
+    "read/problems",
+    "search/changes",
+  ]
+---
+
+# Tester Agent Instructions
+
+You are in Testing Mode.
+
+Primary mission: produce fast, deterministic, behaviour-focused tests that enforce TDD and repository standards.
+
+## Sources of Truth
+
+- Central policies: `.github/copilot-instructions.md`
+- Code review criteria: `docs/engineering/code-review-guidelines.md`
+- PR checklist: `docs/engineering/pull-request-guidelines.md`
+- Optional extended patterns/examples: `.github/agents/Tester.reference.md`
+
+Do not duplicate numeric thresholds from central policies. Reference them.
+
+## Critical Requirements
+
+- Always start with a failing test (RED).
+- Prove RED by running only the new/targeted test first.
+- Implement only the minimum needed for GREEN.
+- Re-run affected tests, then run full suite.
+- Do not ship with failing tests.
+
+## Test Quality Requirements
+
+- Use Arrange / Act / Assert structure. Single blank line between sections. NO comments or TODOs.
+- Keep tests deterministic (no real network, no random nondeterminism, no timing sleeps).
+- Prefer unit tests first; add integration/E2E only when boundary behaviour requires it.
+- Use project test stack: xUnit v3 + Shouldly + NSubstitute.
+- Use `TestContext.Current.CancellationToken` for async tests.
+- Do not test scaffolding/boilerplate code (e.g. generated code, simple getters/setters) unless it contains non-trivial logic.
+- Test observable behaviour, not implementation details. Avoid over-mocking or asserting on private/internal state.
+
+## Scope
+
+- Write new tests for requested behaviour.
+- Improve existing tests for readability and reliability.
+- Add edge/error-path coverage where meaningful.
+- Suggest missing test cases when gaps are evident.
+- No need to show tests before implementation unless user requests. Focus on delivering value, not process.
+
+Do not implement production code unless the user explicitly asks.
+
+## Test-Type Selection
+
+1. Unit test by default for logic/branching.
+2. Integration test for module/adapter/db/http contracts.
+3. E2E test only for critical user journeys.
+
+Heuristic:
+- Bug fix: reproduce at lowest feasible level first.
+- New feature: unit tests for core logic + focused integration for key boundaries; minimal E2E for critical flow.
+
+## TDD Loop (Red → Green → Refactor)
+
+1. Add one failing test.
+2. Run only that test and confirm failure.
+3. Make minimal change to pass.
+4. Run related test project.
+5. Run full suite.
+6. Refactor tests/code while staying green.
+
+## Quality Gates
+
+- Deterministic and isolated tests only.
+- No shared mutable cross-test state.
+- Cover happy path + error path + important edge cases.
+- Prioritize meaningful assertions over superficial coverage.
+- Keep tests maintainable with clear naming and small setup.
+
+## Test Style Requirements
+
+- No comments/TODOs in tests.
+- No `Assert.*`; use Shouldly.
+- Test names must describe behaviour.
+- Prefer behaviour assertions over implementation-detail assertions.
+
+Recommended naming:
+- Class: `{ComponentName}Should`
+- Method: `{behaviour}When{Scenario}` or `{Method}ScenarioExpectedResult`
+
+## Platform-Specific Guidance (Astar OneDrive)
+
+- Validate Onion boundaries in tests (UI→Application→Domain; Infrastructure behind interfaces).
+- Prefer functional outcomes (`Result/Option`) where applicable.
+- For UI tests (Avalonia/ReactiveUI), prioritize ViewModel behaviour and command state.
+- For async/reactive flows, assert completion, cancellation, and error propagation.
+
+## Output Requirements
+
+When delivering test work, include:
+- Bullet points for what was tested:
+  - Key scenarios covered (happy/error/edge).
+- Commands run and results.
+- Any remaining risk/gaps.
+
+## Anti-Patterns to Reject
+
+- Testing private / internal methods
+- Testing implementation details.
+- Time-based flakiness (`Thread.Sleep`, race-prone assertions).
+- Real external calls in unit tests.
+- Weak assertions that only prove non-null/non-throw when richer behaviour is expected.
+
+For comprehensive examples and reusable test templates, see `.github/agents/Tester.reference.md`.
diff --git a/.github/agents/Tester.reference.md b/.github/agents/Tester.reference.md
new file mode 100644
index 0000000..b0f5d11
--- /dev/null
+++ b/.github/agents/Tester.reference.md
@@ -0,0 +1,84 @@
+# Tester Reference (Supplementary)
+
+This file provides optional depth for the Tester agent. The enforceable rules are in:
+
+- `.github/agents/Tester.agent.md`
+- `.github/copilot-instructions.md`
+
+## Quick Test Templates
+
+### Unit test template
+
+```csharp
+public sealed class ComponentShould
+{
+    [Fact]
+    public void ReturnExpectedValueWhenInputIsValid()
+    {
+        var sut = new Component();
+
+        var result = sut.DoWork("input");
+
+        result.ShouldBe("expected");
+    }
+}
+```
+
+### Async test template
+
+```csharp
+[Fact]
+public async Task ReturnFailureWhenCancelled()
+{
+    using var cts = CancellationTokenSource.CreateLinkedTokenSource(TestContext.Current.CancellationToken);
+    cts.Cancel();
+    var sut = new Component();
+
+    var result = await sut.RunAsync(cts.Token);
+
+    result.IsFailure.ShouldBeTrue();
+}
+```
+
+### NSubstitute interaction template
+
+```csharp
+[Fact]
+public async Task CallRepositoryOnceWhenSaving()
+{
+    var repo = Substitute.For<IRepository>();
+    var sut = new Service(repo);
+
+    await sut.SaveAsync(TestContext.Current.CancellationToken);
+
+    await repo.Received(1).SaveAsync(Arg.Any<CancellationToken>());
+}
+```
+
+## What Good Coverage Looks Like
+
+- Happy path behaviour is asserted.
+- Error/failure path behaviour is asserted.
+- Boundary/edge inputs are asserted.
+- Assertions verify outcomes, not internals.
+
+## Test Review Checklist (Compact)
+
+- Uses AAA structure.
+- Names are behaviour-focused.
+- Deterministic and isolated.
+- No comments/TODOs in tests.
+- Uses Shouldly and project conventions.
+- Async tests use `TestContext.Current.CancellationToken`.
+
+## When to Escalate to Integration/E2E
+
+- Contract changes across module boundaries.
+- Serialization/persistence/query behaviour.
+- User-visible workflow spans multiple components.
+
+## Functional Patterns (Astar)
+
+- Prefer verifying `Result` success/failure states explicitly.
+- Prefer verifying `Option` Some/None behaviour explicitly.
+- Include branch assertions for mapped/bound outcomes when behaviour depends on composition.
diff --git a/.github/instructions/backend.instructions.md b/.github/instructions/backend.instructions.md
new file mode 100644
index 0000000..7fad92e
--- /dev/null
+++ b/.github/instructions/backend.instructions.md
@@ -0,0 +1,259 @@
+---
+applyTo: "**/*.java, **/*.py, **/*.cs"
+---
+
+<!-- The above section is called 'frontmatter' and is used to define metadata for the document -->
+<!-- The main content of the markdown file starts here -->
+
+# Backend Development Guidelines
+
+## General Guidelines
+
+Follow idiomatic practices for the chosen programming language and framework. Prioritize writing clean, maintainable, and secure code.
+
+- **Consistency**: Adhere to the existing code style and patterns in the project.
+- **Security**: Implement security best practices, such as input validation, parameterized queries (to prevent SQL injection), and proper authentication/authorization.
+- **Error Handling**: Implement robust error handling and logging to ensure system stability and ease of debugging.
+- **Configuration Management**: Externalize configuration from code. Use environment variables or configuration files. Do not commit secrets to version control.
+- **Testing**: Write unit tests for business logic and integration tests for critical paths. Aim for high test coverage, especially on new code.
+
+## Language-Specific Guidelines
+
+**Note**: This file contains generic guidelines for multiple backend languages. **This project uses C#/.NET exclusively.** Non-C# sections are provided as reference for multi-language teams and may be useful for understanding cross-language patterns.
+
+### Java
+
+- **Build Tools**: Use Maven or Gradle for dependency management.
+- **Coding Style**: Follow the Google Java Style Guide or the Oracle Code Conventions for the Java Programming Language.
+- **Null Handling**: Use `Optional` to avoid `NullPointerException`.
+
+#### Spring Boot
+
+1.  **Project Structure**: Follow the standard Spring Boot project structure (e.g., `src/main/java`, `src/main/resources`).
+2.  **Dependency Management**: Use Spring Boot Starters to simplify dependency management.
+3.  **Configuration**: Use `application.properties` or `application.yml` for configuration settings. Use profiles (`application-{profile}.yml`) for environment-specific configurations.
+4.  **Database Access**: Use Spring Data JPA for database interactions with repositories.
+5.  **REST APIs**: Use `@RestController` for creating RESTful services and DTOs (Data Transfer Objects) to decouple API contracts from domain models.
+6.  **Security**: Use Spring Security for authentication and authorization.
+
+### Python
+
+- **Dependency Management**: Use `pip` with `requirements.txt` or a tool like Poetry or Pipenv.
+- **Coding Style**: Follow PEP 8.
+- **Virtual Environments**: Always use a virtual environment (e.g., `venv`).
+
+#### Django
+
+- **Project Structure**: Follow the standard Django project structure (`manage.py`, project folder, app folders).
+- **ORM**: Use the Django ORM for database interactions.
+- **Settings**: Manage settings for different environments carefully (e.g., `settings/base.py`, `settings/dev.py`, `settings/prod.py`).
+- **Security**: Use Django's built-in security features (e.g., CSRF protection, XSS protection).
+
+#### Flask
+
+- **Project Structure**: Use Blueprints to organize larger applications.
+- **ORM**: Use SQLAlchemy with Flask-SQLAlchemy for database interactions.
+- **Configuration**: Use instance folders for configuration.
+
+### C#/.NET
+
+- **Project Structure**: Follow the standard .NET project structure.
+- **Dependency Management**: Use NuGet for package management.
+- **Coding Style**: Follow the Microsoft C# Coding Conventions.
+- **Async/Await**: Use `async` and `await` for non-blocking I/O operations.
+
+#### ASP.NET Core
+
+1.  **Configuration**: Use `appsettings.json` and environment-specific variants (`appsettings.Development.json`).
+2.  **Dependency Injection**: Use the built-in dependency injection container.
+3.  **ORM**: Use Entity Framework Core for database access.
+4.  **API Development**: Use controllers for API endpoints and follow RESTful principles.
+5.  **Security**: Use ASP.NET Core Identity for authentication and authorization.
+
+<!-- Removed duplicated placeholder sections to avoid conflicts; guidance above already covers Flask, Django, and ASP.NET Core. -->
+
+## API Development
+
+1. **Endpoint Design**: Design RESTful APIs with clear and consistent endpoint structures.
+2. **Request/Response Formats**: Follow the API guidelines for request/response formats (e.g., JSON).
+3. **Versioning**: Implement the API versioning strategy defined in the docs to ensure backward compatibility.
+
+## Performance Optimization
+
+1. **Caching**: Implement caching strategies to reduce database load and improve response times.
+2. **Database Optimization**: Optimize database queries and use indexing where appropriate.
+3. **Asynchronous Processing**: Use asynchronous processing for long-running tasks to improve API responsiveness.
+
+<a name="backend-architecture"></a>
+
+## Architecture & Structure
+
+Adopt a simple, layered architecture to keep boundaries clear and testable:
+
+- Entry (HTTP/CLI/Queue) → Controller/Handler → Service (business logic) → Repository (data access) → External systems.
+- Keep DTOs separate from domain models; map at edges.
+- Inject dependencies through constructors. Avoid singletons and global state.
+
+Framework-specific notes:
+
+- Spring Boot: Controllers (`@RestController`) → Services (`@Service`) → Repos (`@Repository`). Use packages by feature when helpful.
+- Django: Views/ViewSets → Services (plain modules) → ORM Models/Managers. Keep fat models thin services as needed; avoid business logic in views.
+- ASP.NET Core: Controllers → Services (DI) → Repositories (EF Core). Prefer interfaces for services/repositories for testability.
+
+Testing guidance: unit-test services with fakes; integration-test controllers and repositories. See `.github/copilot-instructions.md#quality-policy` for coverage expectations.
+
+<a name="backend-error-handling"></a>
+
+## Error Handling
+
+##### Example: Global Exception Handler (Spring)
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+	@ExceptionHandler(EntityNotFoundException.class)
+	public ResponseEntity<ApiError> handleNotFound(EntityNotFoundException ex) {
+		return ResponseEntity.status(HttpStatus.NOT_FOUND)
+				.body(new ApiError("not_found", ex.getMessage()));
+	}
+}
+```
+
+### Python
+
+- **Dependency Management**: Use `pip` with `requirements.txt` or a tool like Poetry or Pipenv.
+- **Coding Style**: Follow PEP 8.
+- **Virtual Environments**: Always use a virtual environment (e.g., `venv`).
+
+#### Django
+
+- **Project Structure**: Follow the standard Django project structure (`manage.py`, project folder, app folders).
+- **ORM**: Use the Django ORM for database interactions.
+- **Settings**: Manage settings for different environments carefully (e.g., `settings/base.py`, `settings/dev.py`, `settings/prod.py`).
+- **Security**: Use Django's built-in security features (e.g., CSRF protection, XSS protection).
+
+##### Example: Logging Errors via Middleware (Django)
+
+```python
+# core/middleware.py
+class ErrorLoggingMiddleware:
+	def __init__(self, get_response):
+		self.get_response = get_response
+
+	def __call__(self, request):
+		return self.get_response(request)
+
+	def process_exception(self, request, exception):
+		import logging
+		logger = logging.getLogger(__name__)
+		logger.exception("Unhandled error", extra={"path": request.path})
+		return None  # let default handlers run
+```
+
+Add to `MIDDLEWARE` in settings to enable.
+
+#### Flask
+
+- **Project Structure**: Use Blueprints to organize larger applications.
+- **ORM**: Use SQLAlchemy with Flask-SQLAlchemy for database interactions.
+- **Configuration**: Use instance folders for configuration.
+
+##### Example: Error Handler (Flask)
+
+```python
+from flask import Flask, jsonify
+
+app = Flask(__name__)
+
+@app.errorhandler(ValueError)
+def handle_value_error(err):
+	return jsonify({"error": "invalid_input", "message": str(err)}), 400
+```
+
+### C#/.NET
+
+- **Project Structure**: Follow the standard .NET project structure.
+- **Dependency Management**: Use NuGet for package management.
+- **Coding Style**: Follow the Microsoft C# Coding Conventions.
+- **Async/Await**: Use `async` and `await` for non-blocking I/O operations.
+
+#### ASP.NET Core
+
+1.  **Configuration**: Use `appsettings.json` and environment-specific variants (`appsettings.Development.json`).
+2.  **Dependency Injection**: Use the built-in dependency injection container.
+3.  **ORM**: Use Entity Framework Core for database access.
+4.  **API Development**: Use minimal APIs for API endpoints and follow RESTful principles.
+5.  **Security**: Use ASP.NET Core Identity for authentication and authorization.
+
+##### Example: Centralized Exception Handling (ASP.NET Core)
+
+```csharp
+// In Program.cs
+app.UseExceptionHandler(appError =>
+{
+	appError.Run(async context =>
+	{
+		context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+		await context.Response.WriteAsJsonAsync(new { error = "internal_error" });
+	});
+});
+```
+
+<a name="backend-error-handling"></a>
+
+## Error Handling
+
+- Fail fast on invalid inputs; validate at boundaries (controllers) and in domain invariants.
+- Map known exception types to stable error responses; emit machine-parsable `code` fields.
+- Use global exception handling (Spring `@ControllerAdvice`, Django middleware, Flask `errorhandler`, ASP.NET Core `UseExceptionHandler`).
+- Log errors with context (no secrets/PII), include correlation/trace IDs, and prefer structured logs (JSON).
+- Tests must cover error and exception paths (see `.github/copilot-instructions.md#quality-policy`).
+
+<a name="backend-observability"></a>
+
+## Observability
+
+- Logging: structured, leveled logs; include correlation/trace IDs.
+  - Spring: use SLF4J + MDC; Micrometer for metrics (`@Timed`).
+  - Python: stdlib `logging` with structured formatter; expose health endpoints.
+  - .NET: `ILogger<T>` with scopes; OpenTelemetry exporters for traces/metrics.
+- Metrics: instrument hot paths, DB calls, external requests; standard RED/USE metrics.
+- Tracing: propagate trace headers (W3C TraceContext). Use OpenTelemetry SDKs where available.
+
+Return consistent error shapes (code, message, correlationId) and map exceptions to appropriate status codes. Do not leak stack traces to clients.
+
+Examples:
+
+```java
+// Spring: add correlation ID to MDC
+try (MDC.MDCCloseable c = MDC.putCloseable("correlationId", cid)) {
+	log.info("Processing request");
+}
+```
+
+```csharp
+// .NET: log scope with correlation id
+using (logger.BeginScope(new Dictionary<string, object>{{"correlationId", cid}}))
+{
+		logger.LogInformation("Processing request");
+}
+```
+
+<a name="backend-security"></a>
+
+## Security Essentials
+
+- Authentication & Authorization: enforce least privilege; guard all sensitive endpoints.
+- Input validation & output encoding: prevent injection and XSS; use parameterized queries only.
+- Secrets management: never commit secrets; load from env/managed secret stores; rotate regularly.
+- Transport security: enforce HTTPS; set secure headers (HSTS, CSP, X-Frame-Options, X-Content-Type-Options).
+- CSRF/CORS: configure appropriately for web apps and APIs.
+- Dependency hygiene: pin versions; scan with SCA tools; review transitive risks.
+- Data protection: avoid logging PII/secrets; encrypt at rest/in transit where applicable.
+
+References:
+
+- Branch/PR workflow and conventions: `.github/copilot-instructions.md`.
+- Coverage and critical-path rules: `.github/copilot-instructions.md#quality-policy`.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/instructions/bdd-tests.instructions.md b/.github/instructions/bdd-tests.instructions.md
new file mode 100644
index 0000000..7fdc7d8
--- /dev/null
+++ b/.github/instructions/bdd-tests.instructions.md
@@ -0,0 +1,159 @@
+---
+applyTo: "**.feature"
+---
+
+<!--
+SECTION PURPOSE: Repository-wide rules for Gherkin BDD feature files.
+PROMPTING: Provide clear patterns, examples, and enforcement for consistent tests.
+-->
+
+# BDD Test Instructions
+
+<!--
+SECTION PURPOSE: Set global conventions for feature files.
+-->
+
+## Conventions
+
+1. One Feature per file; filename kebab-case matching the feature title slug.
+2. Use Background sparingly for common Given setup; keep scenarios independent.
+3. Prefer concrete, observable behavior over implementation details.
+4. Keep steps business-readable; avoid UI selectors or technical jargon.
+
+<a name="bdd-naming"></a>
+
+### Naming & File Structure
+
+- Filenames: `feature-name.feature` (kebab-case), matching the Feature title slug.
+- Feature titles: imperative, business behavior oriented (e.g., "Sign in to account").
+- Scenario titles: describe outcome (e.g., "Login fails with invalid password").
+- Step definitions: use domain language; keep glue thin and reusable.
+
+<a name="bdd-background-state-tags"></a>
+
+### Background, State, and Tags
+
+- Background: only shared, immutable setup. Avoid modifying global state here.
+- State isolation: each scenario sets its own preconditions; no order dependence.
+- Tags: use `@smoke`, `@regression`, `@wip`, `@negative`, `@slow` to group and control execution.
+- Data: prefer Scenario Outline for variations; keep example tables compact and meaningful.
+
+<!--
+SECTION PURPOSE: Define the minimal contract for a good Scenario.
+PROMPTING: Checklist for scenario completeness and clarity.
+-->
+
+## Scenario Quality Checklist
+
+- Scenario has a meaningful title stating the behavior and outcome.
+- Steps follow Given-When-Then order; And is used only to add detail.
+- Preconditions are explicit; no hidden state from previous scenarios.
+- Data examples: use Scenario Outline when testing variations.
+- Avoid hidden UI details and timing assumptions; assert observable outcomes.
+- Keep nouns/verbs consistent across features.
+
+<!--
+SECTION PURPOSE: Enforce machine-checkable constraints to keep specs healthy.
+-->
+
+<CRITICAL_REQUIREMENT type='MANDATORY'>
+
+- Do not couple steps to UI structure (DOM/XPath). Use domain language.
+- Do not assert multiple outcomes per scenario; keep assertions focused.
+- Keep scenarios ≤ 10 steps to maintain readability and execution speed.
+  </CRITICAL_REQUIREMENT>
+
+<!--
+SECTION PURPOSE: Provide canonical examples for copy/paste and adaptation.
+-->
+
+## Examples
+
+Feature: User login
+As a registered user
+I want to sign in
+So that I can access my account
+
+Background:
+Given a registered user exists
+
+Scenario: Successful login
+Given I am on the sign-in page
+When I sign in with valid credentials
+Then I should see my dashboard
+And I should be greeted by name
+
+Scenario Outline: Login fails with invalid credentials
+Given I am on the sign-in page
+When I sign in with <username> and <password>
+Then I should see an authentication error
+
+    Examples:
+      | username | password |
+      | alice    | wrong    |
+      | bob      | bad      |
+
+<a name="bdd-good-vs-bad"></a>
+
+## Good vs Bad Scenarios
+
+Example 1: Clear, behavior-focused vs UI-coupled
+
+Good:
+
+```
+Scenario: Add item to cart updates total
+  Given a priced item exists
+  And my cart is empty
+  When I add the item to my cart
+  Then my cart total should equal the item price
+```
+
+Bad:
+
+```
+Scenario: Click add button updates total
+  Given I click the button with id "#add-btn"
+  And I wait 3 seconds
+  Then the element ".total" text should be "$9.99"
+```
+
+Example 2: Single outcome vs multiple assertions
+
+Good:
+
+```
+Scenario: Payment declined shows error
+  Given my card is blocked
+  When I attempt to pay
+  Then I should see a decline message
+```
+
+Bad:
+
+```
+Scenario: Payment declined does many things
+  Given my card is blocked
+  When I attempt to pay
+  Then I should see a decline message
+  And my order is cancelled
+  And my basket is emptied
+  And an email is sent
+```
+
+Rationale: Split into separate scenarios to keep each focused and reliable.
+
+<!--
+SECTION PURPOSE: Encourage living docs and CI-ready behavior.
+-->
+
+## Process
+
+1. Start with the happy path scenario; run and see it fail.
+2. Implement the step definitions minimally to pass.
+3. Add edge case scenarios and Scenario Outlines; keep steps reusable.
+4. Wire into CI to run on PRs and gate merges on failures.
+5. Tag scenarios appropriately and configure CI to run fast suites on PRs (e.g., `@smoke`) and full suites nightly.
+6. Keep step definitions DRY; refactor when duplication creeps in.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/instructions/development-tasks.instructions.md b/.github/instructions/development-tasks.instructions.md
new file mode 100644
index 0000000..770b9fc
--- /dev/null
+++ b/.github/instructions/development-tasks.instructions.md
@@ -0,0 +1,369 @@
+# Common Development Tasks
+
+Step-by-step guides for common development tasks in the AStar Dev OneDrive Sync Client.
+
+---
+
+## Adding a New Service
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+All services must be interface-based for testability. Services are automatically registered via source generators using the `[Service]` attribute.
+</PROCESS_REQUIREMENTS>
+
+**Steps**:
+
+1. **Create Interface**: `Infrastructure/Services/I<ServiceName>.cs`
+
+   ```csharp
+   public interface IMyService
+   {
+       Task<Result<Data>> ProcessAsync(string input, CancellationToken ct = default);
+   }
+   ```
+
+2. **Implement Service**: `Infrastructure/Services/<ServiceName>.cs`
+
+   ```csharp
+   [Service(ServiceLifetime.Scoped, As = typeof(IMyService))]
+   public class MyService : IMyService
+   {
+       private readonly IDependency _dependency;
+
+       public MyService(IDependency dependency)
+       {
+           _dependency = dependency;
+       }
+
+       public async Task<Result<Data>> ProcessAsync(string input, CancellationToken ct = default)
+       {
+           // Implementation
+       }
+   }
+   ```
+
+3. **Add `[Service]` Attribute**: Choose appropriate lifetime:
+   - `Singleton`: Stateless, shared across app lifetime
+   - `Scoped`: Per-operation, owns resources (e.g., DbContext)
+   - `Transient`: New instance per injection (rarely used)
+
+4. **Inject in Consumers**: Via constructor parameters
+
+   ```csharp
+   public class Consumer
+   {
+       private readonly IMyService _myService;
+
+       public Consumer(IMyService myService)
+       {
+           _myService = myService;
+       }
+   }
+   ```
+
+5. **Create Tests**: `test/.../MyServiceShould.cs`
+
+   ```csharp
+   public class MyServiceShould
+   {
+       private readonly Mock<IDependency> _mockDependency;
+       private readonly IMyService _sut;
+
+       public MyServiceShould()
+       {
+           _mockDependency = new Mock<IDependency>();
+           _sut = new MyService(_mockDependency.Object);
+       }
+
+       [Fact]
+       public async Task ProcessInputSuccessfully()
+       {
+           // Arrange
+           _mockDependency.Setup(d => d.GetDataAsync(It.IsAny<string>()))
+               .ReturnsAsync(new Data());
+
+           // Act
+           var result = await _sut.ProcessAsync("test");
+
+           // Assert
+           result.IsSuccess.Should().BeTrue();
+       }
+   }
+   ```
+
+6. **Mock in Tests**: Create test doubles via interface
+
+---
+
+## Adding a New Repository
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+Repositories abstract data access. One repository per aggregate/entity. Methods return domain models with `Result<T>` or `Option<T>`. DbContext is scoped to service lifetime.
+</PROCESS_REQUIREMENTS>
+
+**Steps**:
+
+1. **Create Interface**: `Infrastructure/Repositories/I<EntityName>Repository.cs`
+
+   ```csharp
+   public interface IMyEntityRepository
+   {
+       Task<Option<MyEntity>> GetByIdAsync(string id, CancellationToken ct = default);
+       Task<Result<MyEntity>> CreateAsync(MyEntity entity, CancellationToken ct = default);
+       Task<Result<Unit>> UpdateAsync(MyEntity entity, CancellationToken ct = default);
+       Task<Result<Unit>> DeleteAsync(string id, CancellationToken ct = default);
+       Task<IReadOnlyList<MyEntity>> GetAllAsync(CancellationToken ct = default);
+   }
+   ```
+
+2. **Implement Repository**: `Infrastructure/Repositories/<EntityName>Repository.cs`
+
+   ```csharp
+   [Service(ServiceLifetime.Scoped, As = typeof(IMyEntityRepository))]
+   public class MyEntityRepository : IMyEntityRepository
+   {
+       private readonly SyncDbContext _context;
+
+       public MyEntityRepository(SyncDbContext context)
+       {
+           _context = context;
+       }
+
+       public async Task<Option<MyEntity>> GetByIdAsync(string id, CancellationToken ct = default)
+       {
+           var entity = await _context.MyEntities
+               .Include(e => e.RelatedData)  // Eager load relationships
+               .AsNoTracking()               // Read-only optimization
+               .FirstOrDefaultAsync(e => e.Id == id, ct);
+
+           return entity != null ? Option<MyEntity>.Some(entity) : Option<MyEntity>.None();
+       }
+   }
+   ```
+
+3. **Create Entity**: In `Core/Data/Entities/MyEntity.cs`
+
+   ```csharp
+   public class MyEntity
+   {
+       public string Id { get; set; } = string.Empty;
+       public string Name { get; set; } = string.Empty;
+       public DateTime CreatedAt { get; set; }
+
+       // Navigation properties
+       public List<RelatedData> RelatedData { get; set; } = new();
+   }
+   ```
+
+4. **Configure DbContext**: In `SyncDbContext.OnModelCreating()`
+
+   ```csharp
+   modelBuilder.Entity<MyEntity>(entity =>
+   {
+       entity.HasKey(e => e.Id);
+       entity.Property(e => e.Name).IsRequired().HasMaxLength(255);
+       entity.HasIndex(e => e.Name);  // Add indexes for queries
+
+       entity.HasMany(e => e.RelatedData)
+           .WithOne()
+           .HasForeignKey("MyEntityId")
+           .OnDelete(DeleteBehavior.Cascade);
+   });
+   ```
+
+5. **Create Migration**:
+
+   ```bash
+   dotnet ef migrations add AddMyEntity \
+     --project src/AStar.Dev.OneDrive.Sync.Client.Infrastructure \
+     --startup-project src/AStar.Dev.OneDrive.Sync.Client
+   ```
+
+6. **Apply Migration**:
+   ```bash
+   dotnet ef database update \
+     --project src/AStar.Dev.OneDrive.Sync.Client.Infrastructure \
+     --startup-project src/AStar.Dev.OneDrive.Sync.Client
+   ```
+
+---
+
+## Adding a New ViewModel
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+ViewModels must inherit from `ReactiveObject` and use reactive properties. All business logic delegated to services. ViewModels are UI state coordinators, not business logic containers.
+</PROCESS_REQUIREMENTS>
+
+**Steps**:
+
+1. **Create Class**: Inherit from `ReactiveObject`
+
+   ```csharp
+   public class MyViewModel : ReactiveObject
+   {
+       private readonly IMyService _myService;
+       private readonly ObservableAsPropertyHelper<string> _status;
+
+       public MyViewModel(IMyService myService)
+       {
+           _myService = myService;
+
+           // Reactive property binding
+           _status = this.WhenAnyValue(x => x.IsLoading)
+               .Select(isLoading => isLoading ? "Loading..." : "Ready")
+               .ToProperty(this, x => x.Status);
+       }
+
+       public string Status => _status.Value;
+   }
+   ```
+
+2. **Add Properties**: Use reactive properties with `this.WhenAnyValue()`
+
+   ```csharp
+   private bool _isLoading;
+   public bool IsLoading
+   {
+       get => _isLoading;
+       set => this.RaiseAndSetIfChanged(ref _isLoading, value);
+   }
+   ```
+
+3. **Create Commands**: Use `ReactiveCommand` with observables
+
+   ```csharp
+   public ReactiveCommand<Unit, Unit> LoadDataCommand { get; }
+
+   public MyViewModel(IMyService myService)
+   {
+       _myService = myService;
+
+       // Can execute when not loading
+       var canExecute = this.WhenAnyValue(x => x.IsLoading, isLoading => !isLoading);
+
+       LoadDataCommand = ReactiveCommand.CreateFromTask(
+           async () => await LoadDataAsync(),
+           canExecute);
+   }
+
+   private async Task LoadDataAsync()
+   {
+       IsLoading = true;
+       try
+       {
+           var result = await _myService.ProcessAsync("data");
+           // Handle result
+       }
+       finally
+       {
+           IsLoading = false;
+       }
+   }
+   ```
+
+4. **Add Tests**: Mock dependencies via interfaces
+
+   ```csharp
+   public class MyViewModelShould
+   {
+       [Fact]
+       public async Task LoadDataWhenCommandExecuted()
+       {
+           var mockService = new Mock<IMyService>();
+           var viewModel = new MyViewModel(mockService.Object);
+
+           await viewModel.LoadDataCommand.Execute();
+
+           mockService.Verify(s => s.ProcessAsync(It.IsAny<string>()), Times.Once);
+       }
+   }
+   ```
+
+5. **Create View**: XAML with DataContext binding
+   ```xml
+   <UserControl xmlns="https://github.com/avaloniaui"
+                xmlns:vm="using:AStar.Dev.OneDrive.Sync.Client.ViewModels"
+                x:DataType="vm:MyViewModel">
+
+       <StackPanel>
+           <TextBlock Text="{Binding Status}" />
+           <Button Content="Load Data" Command="{Binding LoadDataCommand}" />
+       </StackPanel>
+   </UserControl>
+   ```
+
+---
+
+## Modifying Database Schema
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+All schema changes must go through EF Core migrations. Never modify the database directly. Always review generated migrations before applying. Test migrations on a copy of production data before deploying.
+</PROCESS_REQUIREMENTS>
+
+**Steps**:
+
+1. **Edit Entity** in `Core/Data/Entities/`
+
+   ```csharp
+   public class MyEntity
+   {
+       // Add new property
+       public string NewProperty { get; set; } = string.Empty;
+   }
+   ```
+
+2. **Update DbContext** configuration if needed (in `SyncDbContext.OnModelCreating()`)
+
+   ```csharp
+   modelBuilder.Entity<MyEntity>(entity =>
+   {
+       entity.Property(e => e.NewProperty)
+           .IsRequired()
+           .HasMaxLength(100);
+   });
+   ```
+
+3. **Create Migration**:
+
+   ```bash
+   dotnet ef migrations add AddNewPropertyToMyEntity \
+     --project src/AStar.Dev.OneDrive.Sync.Client.Infrastructure \
+     --startup-project src/AStar.Dev.OneDrive.Sync.Client
+   ```
+
+4. **Review Generated Migration**: Check `Infrastructure/Data/Migrations/`
+   - Verify `Up()` method adds new column correctly
+   - Verify `Down()` method removes column (for rollback)
+   - Add data migrations if needed (e.g., populate new column with default values)
+
+5. **Apply Migration**:
+
+   ```bash
+   dotnet ef database update \
+     --project src/AStar.Dev.OneDrive.Sync.Client.Infrastructure \
+     --startup-project src/AStar.Dev.OneDrive.Sync.Client
+   ```
+
+6. **Update Repository**: Add queries/methods for new properties
+   ```csharp
+   public async Task<IReadOnlyList<MyEntity>> GetByNewPropertyAsync(
+       string newPropertyValue,
+       CancellationToken ct = default)
+   {
+       return await _context.MyEntities
+           .Where(e => e.NewProperty == newPropertyValue)
+           .ToListAsync(ct);
+   }
+   ```
+
+**Rolling Back a Migration**:
+
+```bash
+# List migrations
+dotnet ef migrations list
+
+# Revert to previous migration
+dotnet ef database update PreviousMigrationName
+
+# Remove migration file
+dotnet ef migrations remove
+```
diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md
new file mode 100644
index 0000000..d6d20e3
--- /dev/null
+++ b/.github/instructions/docs.instructions.md
@@ -0,0 +1,200 @@
+---
+applyTo: "**/*.md"
+---
+
+<!--
+Purpose: Repository-wide instructions for authoring documentation. Sets expectations, rules, and workflows that AI assistants and humans must follow.
+Prompting techniques: Uses clear headings, imperative rules, templates, and enforcement blocks to drive consistent outputs.
+-->
+
+# Documentation Instructions
+
+This document provides mandatory guidelines for creating and maintaining project documentation across the repository. It applies to all Markdown files and specializes rules for ADRs, PRDs, and Design docs.
+
+<!--
+Purpose: Define the objectives and boundaries of these instructions.
+Prompting techniques: Scope framing to align behavior and outcomes before execution.
+-->
+
+## Scope and Purpose
+
+- Ensure all docs are clear, consistent, and easy to maintain.
+- Provide a standard workflow for planning, drafting, reviewing, and publishing documentation.
+- Define default structures, formatting rules, and approval gates.
+
+<!--
+Purpose: Establish universal style and clarity rules to apply across all docs.
+Prompting techniques: Prescriptive bullet points with imperative tone for easy compliance.
+-->
+
+## General Guidelines
+
+1. **Structure**: Organize documentation into clear sections with headings and subheadings.
+2. **Clarity**: Use simple, concise language. Avoid unexplained jargon.
+3. **Consistency**: Maintain a consistent style and format throughout the documentation.
+4. **Examples**: Include examples and use cases to illustrate concepts.
+
+<!--
+Purpose: Ensure the assistant gathers critical inputs before drafting.
+Prompting techniques: Input collection checklist with mandatory enforcement gate.
+-->
+
+## Inputs to Collect (before drafting)
+
+- Purpose and scope of the document
+- Target audience (developers, end-users, stakeholders)
+- Key features, behaviors, or decisions to cover
+- Existing related documentation or references
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+- If any inputs are missing or ambiguous, ask targeted questions and pause drafting until clarified.
+- Confirm inferred inputs with the requester before proceeding.
+  </PROCESS_REQUIREMENTS>
+
+<!--
+Purpose: Define the review and approval lifecycle to ensure quality and accountability.
+Prompting techniques: Stage-gated workflow steps; mandatory approval via enforcement block.
+-->
+
+## Document Review & Approval Process
+
+1. **Initial Draft**: Create the first version following the general guidelines.
+2. **Peer Review**: Request reviews from relevant stakeholders and address feedback.
+3. **Approval**: Obtain final approval from the document owner before publishing.
+4. **Publishing**: Place approved docs in the appropriate folder (e.g., `docs/`, `docs/ADRs/`, `plans/`).
+5. **Archiving**: Establish a process for archiving outdated documents while ensuring they remain accessible for reference.
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Do not publish without owner approval.
+- Save documents in their canonical locations with appropriate filenames.
+- Update indices or README links when adding new documents.
+  </CRITICAL_REQUIREMENT>
+
+<!--
+Purpose: Provide a reusable scaffold for docs when the author does not specify a structure.
+Prompting techniques: Template-driven prompting to ensure completeness and logical flow.
+-->
+
+## Documentation Structure Template
+
+- Title
+- Introduction
+- Purpose and Scope
+- Target Audience
+- Key Features / Main Content
+- Examples and Code Snippets
+- Diagrams (if applicable)
+- Maintenance and Update Instructions (if applicable)
+- Conclusion
+- References (if applicable)
+
+<!--
+Purpose: Standardize formatting to maximize readability and toolability.
+Prompting techniques: Prescriptive style guide with concrete conventions (headings, lists, fenced code, links, images).
+-->
+
+## Formatting Guidelines
+
+- Use Markdown with clear headings and subheadings.
+- Prefer bullet points and numbered lists for clarity.
+- Use fenced code blocks for code examples; include language identifiers.
+- Link to related internal docs and authoritative external resources.
+- Embed images/diagrams using Markdown.
+- Ensure proper grammar and spelling.
+- Avoid emojis and informal language.
+
+<!--
+Purpose: Provide specialized content requirements for common document types.
+Prompting techniques: Pattern-based checklists per doc type for consistent outputs.
+-->
+
+## Document Types and Guidance
+
+<!--
+Purpose: ADR-specific required sections and storage conventions.
+Prompting techniques: Checklist of mandatory sections and canonical location/naming.
+-->
+
+### Architectural Decision Records (ADRs)
+
+1. **Purpose**: State the decision and the problem it addresses.
+2. **Context**: Provide background and constraints.
+3. **Options Considered**: List alternatives and why they were rejected or accepted.
+4. **Decision**: Clearly state the chosen approach and rationale.
+5. **Consequences**: Note implications, migration steps, and follow-ups.
+6. **Location & Naming**: Save under `docs/ADRs/` using the repository ADR naming convention and template (`docs/ADRs/adr-template.md`).
+
+<!--
+Purpose: PRD-specific structure to align product documentation with measurable outcomes.
+Prompting techniques: Outcome-focused sections and canonical storage.
+-->
+
+### Product Requirements Documents (PRDs)
+
+1. **Overview**: Summarize the product, purpose, and target audience.
+2. **Goals & Objectives**: Define measurable goals.
+3. **Stakeholders**: List stakeholders and roles.
+4. **Success Criteria**: Define how success will be measured.
+5. **Location & Naming**: Save under `docs/PRDs/` using the repository PRD template (`docs/PRDs/prd-template.md`).
+
+<!--
+Purpose: Design doc structure to capture system architecture and concerns.
+Prompting techniques: Sectioned guidance for architecture, data, APIs, UI, and security; canonical storage.
+-->
+
+### Design Documents
+
+1. **Architecture**: Provide diagrams and component descriptions.
+2. **Data Models**: Describe schemas and relationships.
+3. **APIs**: Document endpoints, contracts, and authentication.
+4. **User Interface**: Include wireframes, mockups, and accessibility notes.
+5. **Security**: Outline security considerations and mitigations.
+6. **Location & Naming**: Save under `docs/design/` with a concise, descriptive filename.
+
+<!--
+Purpose: Define default file formats and locations to reduce ambiguity.
+Prompting techniques: Defaults and canonical paths that tools and assistants can rely on.
+-->
+
+## Saving and Location
+
+- Default format: Markdown (`.md`).
+- Default directory: `/docs/` with a relevant filename when no specialized folder applies.
+- Use specialized directories and templates for ADRs (`docs/ADRs/`), PRDs (`docs/PRDs/`), and Design docs (`docs/design/`).
+
+<!--
+Purpose: Establish acceptance criteria any doc must meet before publication.
+Prompting techniques: Concise quality checklist that is easy to verify automatically.
+-->
+
+## Quality Gates
+
+- All new or updated docs must pass a self-review for accuracy, completeness, and clarity.
+- Ensure links are valid and images/diagrams render correctly in GitHub.
+- Update indexes or README tables of contents where applicable.
+
+<!--
+Purpose: Visualize the documentation workflow and decision points.
+Prompting techniques: Mermaid diagram with loopbacks and explicit approval gate to reinforce process.
+-->
+
+<a name="documentation-process-flow"></a>
+
+## Documentation Process (Flow)
+
+```mermaid
+flowchart TD
+	A[Collect inputs] --> B[Outline structure]
+	B --> C[Draft in clear, concise language]
+	C --> D[Add examples and diagrams]
+	D --> E[Peer review]
+	E --> F{Owner approval?}
+	F -- No --> C
+	F -- Yes --> G[Publish to correct location]
+	G --> H[Link/update indexes]
+	H --> I[Plan maintenance cadence]
+```
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/instructions/frontend.instructions.md b/.github/instructions/frontend.instructions.md
new file mode 100644
index 0000000..e40eadc
--- /dev/null
+++ b/.github/instructions/frontend.instructions.md
@@ -0,0 +1,95 @@
+<!--
+SECTION PURPOSE: Frontmatter defines scope (which files are governed by these rules).
+PROMPTING: Keep the YAML minimal; AI should respect this glob when proposing edits.
+-->
+
+---
+
+## applyTo: "**/\*.cs, **/_.axaml, \*\*/_.razor, \*_/_.axaml.cs
+
+<!--
+SECTION PURPOSE: Introduce mandatory frontend guidance.
+PROMPTING: Clear headings; concise bullets for scanability.
+COMPLIANCE: Treat rules below as defaults unless project overrides exist.
+-->
+
+# Frontend Instructions
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Use AvaloniaUI / ReactiveUI for new code and Windows / components.
+  </CRITICAL_REQUIREMENT>
+
+<!--
+SECTION PURPOSE: Universal rules for all frontend code.
+PROMPTING: Imperative checklist for quick verification.
+-->
+
+## General Guidelines
+
+1. **Code Structure**: Prefer small, reusable components and feature modules.
+2. **Styling**: Follow repo standard (CSS Modules/Tailwind/SCSS). Avoid inline styles except small dynamic cases.
+3. **Accessibility**: Prefer native controls, clear labels, visible focus, sufficient contrast.
+4. **Testing**: Use the project's testing stack (e.g., XUnit.V3). See the Testing section below.
+
+<!--
+SECTION PURPOSE: Expectations when authoring components.
+PROMPTING: Specify contract (props/state), error modes, and data flow norms.
+-->
+
+## Component Development
+
+1. **Properties**: Define with C# properties; use nullable reference types (`string?`) for optional properties. Provide sensible defaults via property initializers or constructors. Use descriptive XML documentation comments on public properties.
+2. **State Management**: Use ReactiveUI patterns - inherit ViewModels from `ReactiveObject`, expose observable state via `IObservable<T>` or reactive properties, and use `WhenAnyValue()` for reactive bindings. Prefer local ViewModel state; elevate to shared services (dependency-injected) only when cross-cutting.
+3. **API Calls**: Use the shared API client; centralize endpoints and schemas; handle errors explicitly with `Result<T>` patterns from `AStar.Dev.Functional.Extensions`.
+4. **Error Handling**: Implement error handling in ViewModels; expose error states via observable properties (e.g., `IObservable<string?> ErrorMessage`); provide user-friendly error messages bound to UI elements.
+
+<!--
+SECTION PURPOSE: Make testing guidance explicit and link to SSOTs (Tester chat mode and BDD instructions).
+PROMPTING: Reference, don't duplicate. Keep actions concrete for frontend.
+-->
+
+## Testing
+
+1. **SSOT References**
+   - Tester chat mode: `.github/agents/Tester.agent.md`
+   - BDD tests instructions: `.github/instructions/bdd-tests.instructions.md`
+
+2. **Unit/UI Tests (default stack: XUnit.V3 + Shouldly Library unless overridden)**
+   - Cover rendering, critical interactions (click, type, submit), and state transitions.
+   - Include accessibility assertions (roles/labels/name, focus management, keyboard nav).
+   - Assert async states: loading, success, and error paths; handle empty data gracefully.
+
+3. **E2E/UI Flows (optional, if project uses Playwright/Cypress)**
+   - Keep scenarios small and stable; tag appropriately (e.g., `@ui`, `@smoke`).
+   - Prefer testids sparingly; select by role/name first.
+
+4. **Coverage Policy**
+   - Follow central Quality & Coverage Policy in `.github/copilot-instructions.md#quality-policy`.
+   - Ensure hot paths and error paths are fully covered (100%).
+
+<!--
+SECTION PURPOSE: Keep apps fast and responsive.
+PROMPTING: Short, actionable techniques.
+-->
+
+## Performance Optimization
+
+1. **Lazy Loading**: Defer large routes and heavy components.
+2. **Memoization**: Use AvaloniaUI's `ReactiveObject` and `ReactiveCommand` patterns to avoid unnecessary work.
+3. **Code Splitting**: Split at route and major component boundaries.
+4. **Minimize Re-renders**: Keep props stable; use selectors and derived memoized data.
+
+<!--
+SECTION PURPOSE: Enforce baseline quality gates.
+PROMPTING: XML block for machine-checkable rules.
+-->
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+- Run lints and tests locally before PR.
+- Include accessibility checks (labels, keyboard nav, focus order) in reviews.
+- Avoid `dynamic` or `object` types; use proper types with nullable reference types (`?`) or explicit type parameters. If unavoidable, annotate with a TODO and reason.
+  </PROCESS_REQUIREMENTS>
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/instructions/implementation-patterns.instructions.md b/.github/instructions/implementation-patterns.instructions.md
new file mode 100644
index 0000000..579cb3b
--- /dev/null
+++ b/.github/instructions/implementation-patterns.instructions.md
@@ -0,0 +1,194 @@
+# Implementation Patterns
+
+Project-specific implementation patterns and common solutions for the AStar Dev OneDrive Sync Client.
+
+---
+
+## Handling Sealed/Unmockable Classes
+
+**Problem**: Some Microsoft libraries (MSAL, Graph) use sealed classes that cannot be mocked directly.
+
+**Solution**: Create wrapper interfaces around sealed classes for testability.
+
+**Examples**:
+
+- `IGraphApiClient` wraps `GraphServiceClient`
+- `IAuthenticationClient` wraps `IPublicClientApplication`
+- `IFileWatcherService` wraps `FileSystemWatcher`
+
+**Pattern**:
+
+```csharp
+// Wrapper interface
+public interface IGraphApiClient
+{
+    Task<DriveItem> GetItemAsync(string accountId, string itemId);
+}
+
+// Implementation wraps sealed class
+[Service(ServiceLifetime.Singleton, As = typeof(IGraphApiClient))]
+public class GraphApiClient : IGraphApiClient
+{
+    private readonly GraphServiceClient _graphClient;
+
+    public async Task<DriveItem> GetItemAsync(string accountId, string itemId)
+    {
+        return await _graphClient.Me.Drive.Items[itemId].GetAsync();
+    }
+}
+```
+
+---
+
+## File Watcher Pattern
+
+**Purpose**: Detect local file system changes in real-time to trigger immediate synchronization.
+
+**Implementation**:
+
+- `FileWatcherService` monitors all configured sync directories
+- Debounces rapid changes (multiple rapid edits = one sync operation)
+- Triggers immediate local → remote upload for detected changes
+- Handles file system events: Created, Changed, Deleted, Renamed
+
+**Key Features**:
+
+- Multi-directory monitoring for multi-account support
+- Debounce threshold: 2 seconds (configurable)
+- Filters out temporary files and system files
+- Thread-safe event handling
+
+---
+
+## Delta Query Pattern
+
+**Purpose**: Efficiently fetch only changed items from OneDrive instead of scanning entire drive.
+
+**Flow**:
+
+1. Fetch changes using Microsoft Graph `/delta` endpoint
+2. Process each changed item (created, modified, deleted)
+3. Extract `cTag` (content tag) from each item for future conflict detection
+4. Store delta token from response for next query
+5. Resume from saved token on next sync (incremental sync)
+
+**Benefits**:
+
+- Dramatically reduces API calls and bandwidth
+- Enables efficient incremental synchronization
+- Automatic pagination handling for large change sets
+- Supports resumption after interruption
+
+**Implementation**:
+
+```csharp
+public async IAsyncEnumerable<DriveItem> GetDeltaChangesAsync(
+    string accountId,
+    string deltaToken,
+    [EnumeratorCancellation] CancellationToken ct = default)
+{
+    var request = string.IsNullOrEmpty(deltaToken)
+        ? _graphClient.Me.Drive.Root.Delta()
+        : _graphClient.Me.Drive.Root.Delta(deltaToken);
+
+    do
+    {
+        var page = await request.GetAsync(cancellationToken: ct);
+
+        foreach (var item in page.Value)
+        {
+            yield return item;
+        }
+
+        // Save delta token for next sync
+        if (page.OdataDeltaLink != null)
+        {
+            await SaveDeltaTokenAsync(accountId, ExtractToken(page.OdataDeltaLink), ct);
+        }
+
+        request = page.OdataNextLink != null
+            ? new DriveItemDeltaRequest(page.OdataNextLink, _graphClient, null)
+            : null;
+
+    } while (request != null);
+}
+```
+
+---
+
+## Conflict Resolution Storage
+
+**Purpose**: Persist unresolved sync conflicts for user review and resolution.
+
+**Storage**: `SyncConflictRepository` persists conflicts to SQLite database with full metadata.
+
+**User Resolution Options**:
+
+1. **Keep Local**: Discard remote version, re-upload local file to OneDrive
+2. **Keep Remote**: Discard local version, re-download remote file from OneDrive
+3. **View Both**: Open both versions side-by-side for manual inspection and decision
+
+**Conflict Record Structure**:
+
+- Account ID
+- File path (local and remote)
+- Conflict detection time
+- Local file metadata (size, modified time, hash)
+- Remote file metadata (size, cTag, modified time)
+- Resolution status (pending, resolved)
+- Resolution choice (if resolved)
+
+**Application**: Resolution is applied during next sync phase:
+
+- Pending conflicts block automatic sync of affected files
+- User must resolve before file can be synced
+- Resolution updates both local and remote state
+- Conflict record marked as resolved with timestamp
+
+---
+
+## Progress Reporting
+
+**Purpose**: Real-time synchronization progress feedback to UI layer.
+
+**Mechanism**: `BehaviorSubject<SyncProgress>` observable stream using Reactive Extensions.
+
+**Reported Metrics**:
+
+- Total files to sync (count)
+- Total bytes to sync (size)
+- Files synced so far (count)
+- Bytes synced so far (size)
+- Current file being processed (name and path)
+- Current sync stage (downloading/uploading)
+- Estimated time remaining (calculated)
+- Sync speed (bytes/second)
+
+**UI Updates**:
+
+- ReactiveUI bindings subscribe to `SyncEngine.Progress` observable
+- Progress throttled to max 10 updates per second to avoid UI flooding
+- Stage transitions reported immediately (download → upload)
+- Errors reported via separate error stream
+
+**Implementation**:
+
+```csharp
+private readonly BehaviorSubject<SyncProgress> _progressSubject = new();
+
+public IObservable<SyncProgress> Progress => _progressSubject
+    .Throttle(TimeSpan.FromMilliseconds(100))  // Max 10 updates/sec
+    .ObserveOn(RxApp.MainThreadScheduler);      // Ensure UI thread
+
+private void ReportProgress(SyncProgress progress)
+{
+    _progressSubject.OnNext(progress);
+}
+```
+
+**Best Practices**:
+
+- Report progress after each file operation (not per-chunk)
+- Calculate percentages based on bytes, not file count (more accurate for mixed file sizes)
+- Include cancellation status in progress updates
+- Clear progress state when sync completes or fails
diff --git a/.github/instructions/performance.instructions.md b/.github/instructions/performance.instructions.md
new file mode 100644
index 0000000..c325b04
--- /dev/null
+++ b/.github/instructions/performance.instructions.md
@@ -0,0 +1,276 @@
+# Performance Guidelines
+
+Performance best practices and optimization strategies for the AStar Dev OneDrive Sync Client.
+
+---
+
+## Sync Performance
+
+### Delta Queries
+
+- **Strategy**: Only fetch changes since last sync (incremental)
+- **Benefit**: Dramatically reduces API calls and data transfer
+- **Implementation**: Use Microsoft Graph `/delta` endpoint with stored delta tokens
+- **Best Practice**: Always store delta token after successful sync for resumption
+
+### Batch Operations
+
+- **Strategy**: Group multiple API calls into batch requests where possible
+- **Benefit**: Reduces network round trips and latency
+- **Implementation**: Use Microsoft Graph `$batch` endpoint for multiple operations
+- **Best Practice**: Batch up to 20 requests per batch (Graph API limit)
+
+### Progress Throttling
+
+- **Strategy**: Limit progress update frequency to UI
+- **Benefit**: Prevents UI flooding and improves responsiveness
+- **Implementation**: Use Rx `Throttle()` operator (100ms throttle = max 10 updates/sec)
+- **Best Practice**: Report progress per file, not per chunk
+
+### Cancellation Support
+
+- **Strategy**: Support mid-sync cancellation to improve user experience
+- **Benefit**: Users can stop long-running syncs without waiting
+- **Implementation**: Pass `CancellationToken` through all async methods
+- **Best Practice**: Check cancellation token before expensive operations
+
+### Connection Pooling
+
+- **Strategy**: Reuse HTTP connections for Graph API calls
+- **Benefit**: Reduces connection establishment overhead
+- **Implementation**: Use singleton `HttpClient` with `IHttpClientFactory`
+- **Best Practice**: Configure max connections per endpoint based on workload
+
+---
+
+## Memory Management
+
+### Streaming
+
+- **Strategy**: Stream large file uploads/downloads instead of buffering
+- **Benefit**: Reduces memory footprint for large files
+- **Implementation**: Use `Stream` with chunked reading/writing
+- **Best Practice**: Use 64KB-1MB chunk size for optimal throughput
+
+**Example**:
+
+```csharp
+await using var fileStream = File.OpenRead(filePath);
+await graphClient.Me.Drive.Items[itemId].Content
+    .PutAsync(fileStream, cancellationToken);
+```
+
+### DbContext Lifetime
+
+- **Strategy**: DbContext scoped to service lifetime (per-operation)
+- **Benefit**: Prevents memory leaks from long-lived contexts
+- **Implementation**: Register `SyncDbContext` as `Scoped` service
+- **Best Practice**: Use `using` blocks or dependency injection for automatic disposal
+
+### File Handles
+
+- **Strategy**: Properly dispose file handles after use
+- **Benefit**: Prevents "file in use" errors and resource exhaustion
+- **Implementation**: Use `using` statements or `await using` for async disposal
+- **Best Practice**: Dispose immediately after use, not at end of method
+
+**Example**:
+
+```csharp
+await using var stream = File.OpenRead(filePath);
+// Use stream
+// Automatically disposed here
+```
+
+### Large Collection Processing
+
+- **Strategy**: Process collections in chunks or use streaming
+- **Benefit**: Prevents loading entire result set into memory
+- **Implementation**: Use `IAsyncEnumerable<T>` or pagination
+- **Best Practice**: Yield return items one at a time for streaming
+
+**Example**:
+
+```csharp
+public async IAsyncEnumerable<DriveItem> GetAllItemsAsync(
+    [EnumeratorCancellation] CancellationToken ct = default)
+{
+    var request = _client.Me.Drive.Root.Children.Request();
+
+    do
+    {
+        var page = await request.GetAsync(ct);
+        foreach (var item in page)
+        {
+            yield return item;  // Stream items
+        }
+        request = page.NextPageRequest;
+    } while (request != null);
+}
+```
+
+---
+
+## Database Performance
+
+### Indexing
+
+- **Strategy**: Add indexes for frequently queried columns
+- **Benefit**: Dramatically improves query performance
+- **Implementation**: Include indexes in Entity Framework migrations
+- **Best Practice**: Index foreign keys, status fields, and timestamp columns
+
+**Example**:
+
+```csharp
+modelBuilder.Entity<SyncItem>(entity =>
+{
+    entity.HasIndex(e => e.AccountId);
+    entity.HasIndex(e => e.SyncStatus);
+    entity.HasIndex(e => e.LastModifiedTime);
+    entity.HasIndex(e => new { e.AccountId, e.SyncStatus }); // Composite index
+});
+```
+
+### Query Optimization
+
+- **Strategy**: Use `Include()` to eager load related entities
+- **Benefit**: Prevents N+1 query problem
+- **Implementation**: Include navigation properties in single query
+- **Best Practice**: Use `ThenInclude()` for nested relationships
+
+**Example**:
+
+```csharp
+var items = await _context.SyncItems
+    .Include(i => i.Conflicts)
+    .ThenInclude(c => c.ResolutionHistory)
+    .Where(i => i.AccountId == accountId)
+    .ToListAsync(ct);
+```
+
+### Batch Updates
+
+- **Strategy**: Update multiple records in single transaction
+- **Benefit**: Reduces database round trips and improves throughput
+- **Implementation**: Use `AddRange()` and `SaveChangesAsync()` once
+- **Best Practice**: Batch up to 1000 records per transaction
+
+**Example**:
+
+```csharp
+var items = await GetItemsToUpdateAsync();
+_context.UpdateRange(items);
+await _context.SaveChangesAsync(ct);
+```
+
+### AsNoTracking for Read-Only Queries
+
+- **Strategy**: Use `AsNoTracking()` for queries that don't need change tracking
+- **Benefit**: Reduces memory overhead and improves query performance
+- **Implementation**: Add `.AsNoTracking()` to LINQ query
+- **Best Practice**: Use for all read-only queries (reporting, display)
+
+**Example**:
+
+```csharp
+var items = await _context.SyncItems
+    .AsNoTracking()  // Read-only, no change tracking
+    .Where(i => i.AccountId == accountId)
+    .ToListAsync(ct);
+```
+
+### Connection Pooling
+
+- **Strategy**: SQLite connection pooling is automatic
+- **Benefit**: Reuses connections across operations
+- **Implementation**: Use connection string with `Pooling=True` (default)
+- **Best Practice**: Use scoped DbContext to return connections to pool quickly
+
+---
+
+## API Rate Limiting
+
+### Respect Rate Limits
+
+- **Strategy**: Monitor and respect Microsoft Graph API rate limits
+- **Benefit**: Prevents throttling and service degradation
+- **Implementation**: Check `Retry-After` header in 429 responses
+- **Best Practice**: Implement exponential backoff with jitter
+
+**Example**:
+
+```csharp
+private async Task<T> ExecuteWithRetryAsync<T>(
+    Func<Task<T>> operation,
+    CancellationToken ct)
+{
+    var retryCount = 0;
+    var maxRetries = 5;
+
+    while (true)
+    {
+        try
+        {
+            return await operation();
+        }
+        catch (ServiceException ex) when (ex.StatusCode == HttpStatusCode.TooManyRequests)
+        {
+            if (retryCount >= maxRetries) throw;
+
+            var delay = ex.ResponseHeaders.RetryAfter?.Delta
+                ?? TimeSpan.FromSeconds(Math.Pow(2, retryCount));
+
+            await Task.Delay(delay, ct);
+            retryCount++;
+        }
+    }
+}
+```
+
+---
+
+## Caching Strategies
+
+### In-Memory Cache
+
+- **Strategy**: Cache frequently accessed, rarely changing data
+- **Benefit**: Reduces database and API calls
+- **Implementation**: Use `IMemoryCache` or `BehaviorSubject<T>`
+- **Best Practice**: Set appropriate expiration based on data volatility
+
+### Database Cache
+
+- **Strategy**: Cache remote file metadata locally
+- **Benefit**: Enables offline conflict detection and faster sync
+- **Implementation**: Store DriveItem metadata in `DriveItemsRepository`
+- **Best Practice**: Invalidate cache on delta sync (cTag changes)
+
+### Delta Token Cache
+
+- **Strategy**: Always persist delta tokens after successful sync
+- **Benefit**: Enables incremental sync and reduces data transfer
+- **Implementation**: Store in `SyncRepository` per account
+- **Best Practice**: Clear token on full re-sync or account re-authentication
+
+---
+
+## Performance Monitoring
+
+### Key Metrics
+
+- Sync duration (total time)
+- Files processed per second
+- Bytes transferred per second
+- API calls per sync operation
+- Database query duration
+- Memory usage (peak and average)
+- CPU usage during sync
+
+### Optimization Targets
+
+- Sync 100 files in < 30 seconds (typical workload)
+- Memory usage < 200MB for 10,000 files
+- API calls < 50 for typical sync (delta query)
+- Database queries < 5ms per operation
+- UI remains responsive during sync (< 100ms frame time)
diff --git a/.github/instructions/style-guidelines.instructions.md b/.github/instructions/style-guidelines.instructions.md
new file mode 100644
index 0000000..0712ea8
--- /dev/null
+++ b/.github/instructions/style-guidelines.instructions.md
@@ -0,0 +1,100 @@
+---
+applyTo: "**/*.cs"
+---
+
+Coding standards and style guidelines / preferences for C# files in this repository that AI must follow.
+
+## Naming Conventions
+
+- **Public members**: PascalCase (e.g., `MyClass`, `MyMethod`, `MyProperty`)
+- **Private members**: camelCase (e.g., `myVariable`, `myMethod`)
+- **Private fields**: \_camelCase with underscore prefix (e.g., `_fieldName`)
+- **Constants**: CONSTANT_CASE or PascalCase
+- Use meaningful names that clearly convey purpose; avoid abbreviations unless widely understood
+- Use `nameof()` for parameter names in exceptions and logging
+
+## Namespaces
+
+- Use file-scoped namespaces.
+- Namespace names should follow the pattern: Company.Project.Module (e.g., Contoso.Sales.Reporting).
+- Avoid unnecessary nested namespaces; keep the structure flat when possible.
+
+## Classes and Methods
+
+- Define one class per file, and name the file after the class.
+- Follow SOLID principles for class and method design.
+- Keep classes focused on a single responsibility.
+- Ensure good cohesion within classes and methods (related functionality grouped together).
+- Ensure low coupling between classes and methods.
+- Ensure methods do one thing and do it well.
+- Keep methods short; ideally under 20 lines.
+- Use meaningful names for classes and methods that clearly convey their purpose.
+- Put all method / constructor overloads together in the same order as their parameters.
+- Put all method / constructor parameters on one line when possible; otherwise, wrap parameters to multiple lines but avoid 1 parameter per line.
+- Use expression-bodied members for simple methods and properties.
+- Keep method and constructor parameters to a minimum (ideally <5 parameters); prefer using parameter objects when multiple parameters are needed.
+- Avoid long parameter lists; consider using the Builder pattern for complex object construction.
+- Use dependency injection for managing dependencies (no newing up services inside classes).
+- Prefer composition over inheritance.
+- Avoid deep nesting; use early returns and guard clauses.
+- Do not use regions or #pragma to hide code; refactor instead.
+- Never comment within methods or private members; if a comment is needed, it likely indicates the method is doing too much and should be refactored into smaller, more focused methods. Instead of comments, strive for self-explanatory code through clear naming and small method sizes.
+
+## Immutability
+
+- Prefer immutable data structures and objects where possible.
+- Prefer `record` types for immutable data models and DTOs.
+- Use `class` for entities with behavior or mutable state.
+- Use `init` properties when immutability is desired.
+- Use immutable collections: `IReadOnlyList<T>`, `IReadOnlyCollection<T>`, `IReadOnlyDictionary<TKey, TValue>`.
+- Use `with` expressions to create modified copies of immutable objects.
+
+## Record Design
+
+- Define record properties on the same line with the record declaration when possible.
+- Accompany each record `<name>` with a corresponding `<name>Factory` static factory class.
+- Place the factory class in the same file as the record it creates.
+- Expose static `Create` methods on the factory class for constructing instances of the record.
+- Place argument validation logic within the factory methods.
+- Never use the public constructor of a record directly; always use the factory methods.
+- Use immutable collections (e.g., `IReadOnlyList<T>`, `IReadOnlyDictionary<TKey, TValue>`) for record properties that hold multiple values.
+- Avoid methods on records; use extension methods instead for any behavior related to the record.
+
+## Discriminated Unions
+
+- Use records with inheritance to model discriminated unions.
+- Define an abstract base record for the union type and derive specific case records from it.
+- Place all case records in the same file as the base record.
+- Define one static factory class per discriminated union type.
+- Expose static `Create` methods on the factory class for constructing instances of each case record.
+
+## Variables and Constants
+
+- Use `var` when the type is obvious from the right-hand side; otherwise use explicit types for clarity.
+- Use `const` for compile-time constants.
+- Use `static readonly` for runtime constants.
+- Avoid magic strings and numbers; use constants or enums instead.
+
+## Collections and Data Structures
+
+- Use `IEnumerable<T>` for collections that do not require indexing.
+- Use `IReadOnlyList<T>` or `IReadOnlyCollection<T>` when immutability is desired.
+- Use `StringBuilder` for concatenating multiple strings in loops or when performance is critical; otherwise use string interpolation for readability.
+- Use Collection Initializers and Object Initializers for cleaner code when creating collections and objects.
+
+## Control Flow and Logic
+
+- Use pattern matching and switch expressions for clearer and more concise code when dealing with multiple conditions.
+- Null checking with null-coalescing operators (`??`, `??=`, `?.`).
+- Use `ArgumentNullException` (or `ArgumentNullException.ThrowIfNull`) in public constructors and methods.
+
+## Test Classes
+
+- Name test classes with the suffix `Should` (e.g., `OrderServiceShould`).
+- Organize test methods using the `<Action><Result>[<Exception>]` naming convention (e.g., `ReturnCorrectSumWhenMultipleItemsExist`). This pattern helps clarify the action being tested, the expected result, and any exceptions that may be thrown.
+- Use the Arrange-Act-Assert (AAA) pattern within test methods to structure the code clearly. Divide the method into three distinct sections: setup (Arrange), execution (Act), and verification (Assert). Do not comment these sections; the structure should be clear from the code itself. Separate these sections with a single blank line for readability.
+- Use test data builders to create complex test objects, enhancing readability and maintainability of tests.
+- Avoid logic in test methods; keep tests simple and focused on behavior verification.
+- Use Shouldly for more readable and expressive assertions in tests.
+- Use NSubstitute for mocking dependencies in tests. Avoid mocking when possible; prefer using real instances or test doubles.
+- Never add XML documentation or comments to test classes or test methods.
diff --git a/.github/instructions/troubleshooting.instructions.md b/.github/instructions/troubleshooting.instructions.md
new file mode 100644
index 0000000..bfee7a3
--- /dev/null
+++ b/.github/instructions/troubleshooting.instructions.md
@@ -0,0 +1,256 @@
+# Debugging & Troubleshooting
+
+Common issues, debugging techniques, and troubleshooting guides for the AStar Dev OneDrive Sync Client.
+
+---
+
+## Debug Logging
+
+The application includes comprehensive debug logging infrastructure for troubleshooting sync issues.
+
+### Accessing Debug Logs
+
+**UI Access**:
+
+- Navigate to DebugLogs view in the application
+- Filter by account, date range, log level, or search text
+- Export logs to file for sharing or analysis
+
+**Database Access**:
+
+```sql
+SELECT * FROM DebugLogs
+WHERE AccountId = 'account-id'
+  AND Timestamp > datetime('now', '-1 hour')
+ORDER BY Timestamp DESC;
+```
+
+### Adding Debug Logs
+
+**Entry/Exit Logging**:
+
+```csharp
+await DebugLog.EntryAsync(
+    DebugLogMetadata.Services.MyService.MyMethod,
+    accountId,
+    cancellationToken);
+
+// Method implementation
+
+await DebugLog.ExitAsync(
+    DebugLogMetadata.Services.MyService.MyMethod,
+    accountId,
+    cancellationToken);
+```
+
+**Informational Logging**:
+
+```csharp
+await DebugLog.LogInfoAsync(
+    "MyService.MyMethod",
+    accountId,
+    $"Processing {itemCount} items",
+    cancellationToken);
+```
+
+**Error Logging**:
+
+```csharp
+await DebugLog.LogErrorAsync(
+    "MyService.MyMethod",
+    accountId,
+    exception,
+    "Failed to process items",
+    cancellationToken);
+```
+
+**Performance Logging**:
+
+```csharp
+using var perfLogger = await DebugLog.StartPerformanceLogAsync(
+    "MyService.MyMethod",
+    accountId,
+    cancellationToken);
+
+// Code to measure
+
+// Automatically logs duration on disposal
+```
+
+### Log Levels
+
+- **Trace**: Method entry/exit, detailed flow
+- **Debug**: Detailed diagnostic information
+- **Info**: General informational messages
+- **Warning**: Warning messages (recoverable issues)
+- **Error**: Error messages (exceptions, failures)
+- **Fatal**: Fatal errors (application crashes)
+
+---
+
+## Common Issues
+
+### Sync Not Starting
+
+**Symptoms**: Sync button appears disabled or sync does not progress.
+
+**Troubleshooting**:
+
+1. Check account authentication status in Accounts view
+2. Verify sync folder is selected in Configuration
+3. Check if another sync operation is in progress
+4. Review debug logs for authentication errors
+5. Ensure network connectivity to OneDrive
+
+**Solutions**:
+
+- Re-authenticate account if token expired
+- Select sync folder if none configured
+- Wait for current sync to complete
+- Check firewall/proxy settings
+
+### Conflicts Not Detected
+
+**Symptoms**: Files sync without conflict prompt when both local and remote changed.
+
+**Troubleshooting**:
+
+1. Verify `cTag` is being stored for remote files
+2. Check local file `mtime` (modification time) is accurate
+3. Review conflict detection threshold (60 seconds)
+4. Check debug logs for conflict detection logic
+5. Verify file metadata is being tracked in database
+
+**Solutions**:
+
+- Ensure database migrations are up-to-date
+- Verify file system timestamps are correct
+- Check if files are within conflict threshold window
+- Review `SyncConflictRepository` for pending conflicts
+
+### Database Locked
+
+**Symptoms**: "Database is locked" error messages.
+
+**Troubleshooting**:
+
+1. Check if multiple application instances are running
+2. Verify no other process has database file open
+3. Check for unfinished transactions
+4. Review connection string configuration
+5. Check disk space and permissions
+
+**Solutions**:
+
+- Close all running instances of the application
+- Restart application (closes lingering connections)
+- Check for stuck background sync operations
+- Verify SQLite WAL mode is enabled for concurrency
+
+### Graph API Errors
+
+**Symptoms**: API calls fail with HTTP errors (401, 403, 429, 500, etc.)
+
+**Troubleshooting**:
+
+1. **401 Unauthorized**: Check token expiration, re-authenticate
+2. **403 Forbidden**: Verify API permissions (Files.ReadWrite.All)
+3. **429 Too Many Requests**: Rate limit exceeded, implement backoff
+4. **500 Internal Server Error**: Temporary Microsoft service issue, retry
+5. Review Graph API response headers for additional information
+
+**Solutions**:
+
+- Implement exponential backoff for retries
+- Cache frequently accessed data to reduce API calls
+- Use delta queries to minimize data transfer
+- Monitor rate limits and adjust sync frequency
+- Check Microsoft 365 Service Health Dashboard
+
+---
+
+## Running Specific Tests
+
+### All Tests in a Project
+
+```bash
+dotnet test test/AStar.Dev.OneDrive.Sync.Client.Infrastructure.Tests.Unit/
+```
+
+### Specific Test Class
+
+```bash
+dotnet test --filter WindowPreferencesServiceShould
+```
+
+### Specific Test Method
+
+```bash
+dotnet test --filter "FullyQualifiedName~WindowPreferencesServiceShould.ReturnNullWhenNoPreferencesExist"
+```
+
+### Tests by Category
+
+```bash
+dotnet test --filter "Category=Integration"
+```
+
+### Watch Mode (Auto-Rerun on Changes)
+
+```bash
+dotnet watch test
+```
+
+### With Coverage
+
+```bash
+dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
+```
+
+### Verbose Output
+
+```bash
+dotnet test --logger "console;verbosity=detailed"
+```
+
+---
+
+## Performance Profiling
+
+### Using dotnet-trace
+
+```bash
+# Start recording
+dotnet trace collect --process-id <pid> --providers Microsoft-Windows-DotNETRuntime
+
+# Stop with Ctrl+C
+# Analyze trace with PerfView or Visual Studio
+```
+
+### Memory Profiling
+
+```bash
+# Install dotMemory or dotMemory Unit
+# Profile specific test or application startup
+# Look for memory leaks, large allocations, GC pressure
+```
+
+### CPU Profiling
+
+```bash
+# Use Visual Studio Performance Profiler
+# Or dotnet-counters for real-time metrics
+dotnet counters monitor --process-id <pid>
+```
+
+---
+
+## Logging Best Practices
+
+1. **Log at appropriate levels**: Don't use Error for warnings, Info for debug details
+2. **Include context**: Always include account ID, file paths, operation IDs
+3. **Avoid logging sensitive data**: Never log tokens, passwords, or personal data
+4. **Use structured logging**: Pass parameters for structured queries
+5. **Log exceptions properly**: Include full exception details (message, stack trace, inner exceptions)
+6. **Avoid excessive logging**: Don't log in tight loops or per-file in batch operations
+7. **Clean up logs**: Implement log retention policy (30 days default)
diff --git a/.github/prompts/README.md b/.github/prompts/README.md
new file mode 100644
index 0000000..3849b54
--- /dev/null
+++ b/.github/prompts/README.md
@@ -0,0 +1,38 @@
+# Custom Copilot Prompts
+
+This directory contains reusable prompt files that extend Copilot Chat with repeatable tasks (e.g., "Write ADR", "Write PRD"). Prompts standardize how assistants operate, capture inputs, and produce consistent outputs.
+
+## Custom prompts in this repository
+
+- [/copilot-setup-check](copilot-setup-check.prompt.md)
+- [/write-adr](write-adr.prompt.md)
+- [/write-docs](write-docs.prompt.md)
+- [/write-ears-spec](write-ears-spec.prompt.md)
+- [/write-prd](write-prd.prompt.md)
+
+## How to use
+
+- In Copilot Chat, type the prompt name or pick it from the quick actions list.
+- Many prompts can be invoked like a slash command (e.g., `/write-adr`). If your IDE surfaces prompt files differently, open the prompt and follow its inputs section.
+- Provide required inputs when asked (see the Inputs section inside each prompt). Defaults are applied when permitted.
+
+## Creating a new prompt
+
+- Copy an existing `.prompt.md` file as a starting point.
+- Set a clear `description` and the minimal `tools` needed.
+- Add an Inputs section with `${input:...}` placeholders and validation rules.
+- Define output structure and quality gates so results are consistent and reviewable.
+
+## Hints
+
+Within a prompt file, you can reference variables by using the `${variableName}` syntax. You can reference the following variables:
+
+- Workspace variables - `${workspaceFolder}`, `${workspaceFolderBasename}`
+- Selection variables - `${selection}`, `${selectedText}`
+- File context variables - `${file}`, `${fileBasename}`, `${fileDirname}`, `${fileBasenameNoExtension}`
+- Input variables - `${input:variableName}`, `${input:variableName:placeholder}` (pass values to the prompt from the chat input field)
+
+## Official Docs
+
+- [Visual Studio Code custom prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/copilot-setup-check.prompt.md b/.github/prompts/copilot-setup-check.prompt.md
new file mode 100644
index 0000000..83c01f0
--- /dev/null
+++ b/.github/prompts/copilot-setup-check.prompt.md
@@ -0,0 +1,184 @@
+---
+agent: "agent"
+description: "Evaluate repository Copilot configuration and provide optimization recommendations."
+tools: ["search/codebase", "search", "edit/editFiles", "search/usages", "read/problems", "search/changes"]
+---
+
+<!-- Top-level section: Defines the primary task (evaluate Copilot setup) and sets expectations for comprehensive analysis and actionable recommendations. -->
+
+# Copilot Setup Evaluation
+
+Perform a comprehensive evaluation of the repository's GitHub Copilot and AI agent configuration. Analyze the setup quality and provide specific recommendations for optimization.
+
+<!-- Analysis scope: Defines what components will be evaluated and the depth of analysis required. -->
+
+## Evaluation Scope
+
+This evaluation will assess:
+
+- **.github/copilot-instructions.md** - Copilot-specific configuration and guidelines
+- **.github/agents/** - Custom conversational behaviors and specialized modes
+- **.github/prompts/** - Reusable prompt templates and slash commands
+- **.github/instructions/** - Language and domain-specific coding guidelines
+- **Repository structure** - Overall organization and documentation completeness
+
+<!-- Evaluation criteria: Establishes the standards and best practices against which the setup will be measured. -->
+
+## Evaluation Criteria
+
+### Core Configuration Quality
+
+- **Completeness**: All essential files present and properly structured
+- **Clarity**: Instructions are unambiguous and well-documented
+- **Consistency**: Naming conventions and formatting standards followed
+- **Specificity**: Guidelines are actionable and project-specific
+- **Maintainability**: Configuration is organized for long-term maintenance
+
+### Advanced Setup Features
+
+- **Custom agents**: Specialized conversational behaviors for different contexts
+- **Prompt Templates**: Reusable templates for common development tasks
+- **Domain Instructions**: Language and framework-specific coding guidelines
+- **Workflow Integration**: Alignment with development processes and branching strategy
+
+<!-- Analysis methodology: Defines the systematic approach for conducting the evaluation. -->
+
+## Analysis Process
+
+### Phase 1: Core Files Assessment
+
+1. **For each file type, check existence and quality**
+   - Verify presence and structure
+   - Assess clarity of repository context
+   - Evaluate AI agent guidance completeness
+   - Check for conflicting instructions warning mechanisms
+   - Verify effectiveness of XML semantic tags reinforcing critical requirements
+   - Suggest improvements for clarity and completeness
+   - Suggest enhancements for maintainability and organization
+   - Suggest additions for missing best practices
+   - Suggest removal of redundant or conflicting content
+   - Suggest reinforcements (e.g. XML, Mermaid) for critical policies
+
+2. **Evaluate .github/copilot-instructions.md**
+   - Verify comprehensive project methodology coverage
+   - Assess branching strategy and workflow definitions
+   - Check commit message and naming conventions
+   - Evaluate generic coding standards and quality requirements
+
+### Phase 2: Advanced Configuration Review
+
+3. **Analyze custom agents**
+   - Count and categorize existing agents
+   - Assess relevance to project needs
+   - Check for mode-specific optimization
+   - Evaluate documentation quality
+   - Evaluate conflicts with core instructions, custom instructions (per file type), or custom prompts
+
+4. **Review prompt templates**
+   - Inventory available slash commands
+   - Assess prompt structure and parameterization
+   - Check tool integration and capability coverage
+   - Evaluate reusability and maintenance
+   - Evaluate conflicts with core instructions, custom instructions (per file type), or custom agents
+
+5. **Examine instruction files**
+   - Catalog language/domain-specific instructions
+   - Assess coverage of technology stack and frameworks
+   - Evaluate clarity and actionability of language/framework specific instructions
+   - Check alignment with project requirements
+   - Evaluate specificity and actionability
+   - Evaluate specific coding standards and quality requirements
+   - Evaluate conflicts with core instructions, custom agents, or custom prompts
+
+### Phase 3: Integration and Optimization
+
+6. **Repository structure alignment**
+   - Verify .github directory organization
+   - Check cross-reference consistency
+   - Assess documentation completeness
+   - Evaluate discoverability of configuration
+
+<!-- Reporting requirements: Defines the format and content of the evaluation output. -->
+
+## Reporting Requirements
+
+### Evaluation Report Structure
+
+#### 1. Executive Summary
+
+- Overall setup maturity score (1-10)
+- Top 3 strengths identified
+- Top 3 improvement opportunities
+- Priority level assessment (Critical/High/Medium/Low)
+
+#### 2. Detailed Findings
+
+**Core Configuration Analysis:**
+
+- File presence checklist with status indicators
+- Content quality assessment for each core file
+- Specific gaps or issues identified
+- Compliance with best practices
+
+**Advanced Features Assessment:**
+
+- Feature utilization analysis
+- Optimization opportunities
+- Missing capabilities assessment
+- Integration quality evaluation
+
+#### 3. Actionable Recommendations
+
+**Immediate Actions (Critical Priority):**
+
+- Missing core files to create
+- Critical configuration issues to fix
+- Essential documentation to add
+
+**Short-term Improvements (High Priority):**
+
+- Advanced features to implement
+- Configuration optimizations to apply
+- Documentation enhancements to make
+
+**Long-term Enhancements (Medium Priority):**
+
+- Advanced customizations to consider
+- Workflow integrations to explore
+- Maintenance procedures to establish
+
+#### 4. Implementation Guidance
+
+- Step-by-step action plan
+- Resource requirements and effort estimates
+- Dependencies and prerequisites
+- Success metrics and validation criteria
+
+<!-- Quality assurance: Ensures the evaluation meets professional standards and provides genuine value. -->
+
+## Quality Standards
+
+### Analysis Depth Requirements
+
+- Examine actual file contents, not just presence
+- Assess practical usability, not just theoretical completeness
+- Consider project-specific context and requirements
+- Provide specific, actionable recommendations with examples
+
+### Professional Reporting
+
+- Use clear, non-technical language for executive summary
+- Provide technical details for implementation guidance
+- Include concrete examples and code snippets where helpful
+- Structure for both immediate action and strategic planning
+
+### Validation and Accuracy
+
+- Cross-reference findings across multiple files
+- Verify recommendations against established best practices
+- Ensure suggestions are feasible and properly prioritized
+- Include rationale for all major recommendations
+
+Execute this evaluation systematically and provide a comprehensive report that enables the repository maintainers to optimize their Copilot and AI agent configuration effectively.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/create-readme.prompt.md b/.github/prompts/create-readme.prompt.md
new file mode 100644
index 0000000..c9d4fe6
--- /dev/null
+++ b/.github/prompts/create-readme.prompt.md
@@ -0,0 +1,49 @@
+---
+agent: 'agent'
+description: 'Create a README.md file for the project'
+---
+
+# Create README Prompt
+
+Primary objective: produce a concise, high-signal `README.md` that is attractive, accurate, and useful for first-time contributors/users.
+
+## Sources of Truth
+
+- Project standards: `.github/copilot-instructions.md`
+- Architecture/details to summarize: `docs/implementation-overview.md`, `docs/implementation-plan.md`
+
+## Required Output
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Review the repository/workspace before writing.
+- Keep the README concise and practical; avoid emoji overuse.
+- Do not include sections that belong in dedicated files (`LICENSE`, `CONTRIBUTING`, `CHANGELOG`, etc.).
+- Use GFM formatting.
+- Use GitHub admonitions where they improve clarity.
+- Include project logo/icon in header if available.
+- Include a `Features` section.
+- Include a `Getting Started` section with install/run/use basics.
+- Include badges near the top: Build, SonarCloud, and CodeQL (placeholder values are acceptable).
+
+</CRITICAL_REQUIREMENT>
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+1. Inspect repository structure and docs for accurate content.
+2. Draft a clear section structure before writing.
+3. Verify links/paths and command examples are valid for this repository.
+4. Keep wording specific to this project and avoid generic filler.
+
+</PROCESS_REQUIREMENTS>
+
+## Suggested Section Order
+
+1. Title + logo
+2. GitHub and SonarCloud Badges
+3. Short project summary
+4. Features
+5. Getting Started
+6. Architecture (brief, with links)
+7. Project Structure (brief)
+8. Documentation links
\ No newline at end of file
diff --git a/.github/prompts/snippets/prd-success-metrics.snippet.md b/.github/prompts/snippets/prd-success-metrics.snippet.md
new file mode 100644
index 0000000..abf77db
--- /dev/null
+++ b/.github/prompts/snippets/prd-success-metrics.snippet.md
@@ -0,0 +1,41 @@
+# Success Metrics (Snippet)
+
+Use this structure to define SMART metrics that tie directly to Goals and Acceptance Criteria. Provide at least 3 metrics.
+
+For each metric, fill these fields:
+
+- Metric: [Name/short description]
+- Baseline: [Current value, with date/source]
+- Target: [Numeric goal and direction]
+- Timeframe: [By when; date or period]
+- Datasource: [Where/how it’s measured]
+- Owner: [Role/team accountable]
+- Guardrails: [Boundaries to prevent regressions]
+
+Example metrics:
+
+1) Metric: Week 1 Activation Rate
+   - Baseline: 42% (as of 2025-08-31; Snowflake dashboard ABC)
+   - Target: 55%
+   - Timeframe: By end of Q4 2025
+   - Datasource: Product analytics (Amplitude), event: user_activated
+   - Owner: Growth PM
+   - Guardrails: NPS does not drop below 45; Support volume +< 10%
+
+2) Metric: Onboarding Time (p50)
+   - Baseline: 11m 30s (2025-08; internal telemetry)
+   - Target: 7m 00s
+   - Timeframe: By 2026-01-31
+   - Datasource: Backend logs (Grafana Loki), derived dashboard PRD-ONB-01
+   - Owner: Onboarding team
+   - Guardrails: Error rate stays ≤ 0.5%; Accessibility score ≥ 95
+
+3) Metric: Uptime (SLA)
+   - Baseline: 99.80% (rolling 30d)
+   - Target: ≥ 99.90%
+   - Timeframe: Continuous; measured monthly
+   - Datasource: Uptime monitoring (Pingdom)
+   - Owner: SRE
+   - Guardrails: Mean Time to Recovery ≤ 15m; No P0 incidents from this change
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/write-adr.prompt.md b/.github/prompts/write-adr.prompt.md
new file mode 100644
index 0000000..53a8706
--- /dev/null
+++ b/.github/prompts/write-adr.prompt.md
@@ -0,0 +1,88 @@
+---
+agent: "agent"
+description: "Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation."
+tools:
+  [
+    "search/codebase",
+    "search/usages",
+    "read/problems",
+    "search/changes",
+    "read/terminalSelection",
+    "read/terminalLastCommand",
+    "web/fetch",
+    "search/searchResults",
+    "edit/editFiles",
+    "search",
+    "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection",
+  ]
+---
+
+<!-- Top-level section: Defines the primary task (create an ADR) and sets expectations for structured, AI-optimised output. Techniques: imperative directives, variable interpolation (${input:...}) to parameterise the decision title, and a rule to request more context when inputs are insufficient. -->
+
+# Create Architectural Decision Record
+
+Create an ADR document for `${input:DecisionTitle}` using structured formatting optimised for AI consumption and human readability. If you do not have enough information to create the ADR, ask the user for more context.
+
+If you are not using a branch, create a new branch named `adr/[brief-title-slug]` where `[brief-title-slug]` is a short, hyphenated version of the decision title.
+
+<!-- Governance placeholder: Introduces a section to capture the review/approval workflow for ADRs. Techniques: heading as a stage-gate cue; encourages documenting process ownership and criteria, even if content is populated later. -->
+
+## ADR approval process
+
+<!-- Inputs section: Enumerates required data for ADR generation with explicit parameter placeholders. Techniques: bold labels for emphasis and ${input:...} tokens to drive prompt-time collection and mapping. -->
+
+## Inputs
+
+- **Context**: `${input:Context}`
+- **Decision**: `${input:Decision}`
+- **Alternatives**: `${input:Alternatives}`
+- **Stakeholders**: `${input:Stakeholders}`
+
+<!-- Validation gate: Specifies preconditions before proceeding, ensuring completeness and reducing ambiguity. Techniques: conditional prompting (ask for missing items) and explicit instruction to halt until inputs are provided. -->
+
+## Input Validation
+
+If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide information for each missing item before proceeding with ADR generation.
+
+<!-- Quality rules: Defines content and formatting standards the ADR must satisfy. Techniques: imperative bullet list, explicit inclusion of pros/cons, rejection rationale, machine-parsable structuring, and coded bullet point convention (e.g., ABC-001). -->
+
+## Requirements
+
+- Use precise, unambiguous language
+- Follow standardized ADR format with front matter
+- Include both positive and negative consequences
+- Document alternatives with rejection rationale
+- Structure for machine parsing and human reference
+- Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections
+
+The ADR must be saved in the `docs/ADRs/` directory using one of these validated naming conventions:
+
+1. Preferred (sequential): `adr-NNNN-[brief-title-slug].md`
+   - NNNN is the next monotonically increasing 4-digit number discovered from existing files (e.g., next after `adr-0027-*.md` is `adr-0028-...`).
+
+2. Allowed fallback (timestamp): `adr-YYYYMMDD-[brief-title-slug].md` or `adr-YYYYMMDD-HHMM-[brief-title-slug].md`
+   - Use this only if a sequence cannot be computed (e.g., empty folder, read restriction), or when a timestamp policy is explicitly preferred.
+
+In all cases, ensure the file is created under `docs/ADRs/` and that the filename slug matches the decision title succinctly.
+
+<!-- Template compliance: Directs the assistant to conform to a canonical ADR template and correct front matter, ensuring consistency and toolability. Techniques: explicit file path reference and mandate to fill all sections. -->
+
+## Required Documentation Structure
+
+The documentation file must follow the template specified in `docs/ADRs/adr-template.md`, ensuring that all sections are filled out appropriately. The front matter for the Markdown must be structured correctly as per the template.
+
+## Save & Versioning Rules
+
+1. Discover existing ADRs in `docs/ADRs/` matching `adr-*.md`.
+2. If one or more sequential files exist, compute next NNNN and propose `adr-NNNN-[slug].md`.
+3. If no sequential files exist or computation fails, propose timestamped `adr-YYYYMMDD-[slug].md` (or `-HHMM-` variant).
+4. Validate the save path is exactly `docs/ADRs/` (reject other directories).
+5. Set front matter `date` to today in `YYYY-MM-DD` and ensure `status` is present.
+6. After saving, confirm the file exists and report the final path.
+
+## Commit & Branching
+
+- If not already on a feature branch, create `adr/[brief-title-slug]` before saving.
+- Commit message should follow Conventional Commits, e.g.: `docs: add ADR NNNN <Decision Title>`.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/write-docs.prompt.md b/.github/prompts/write-docs.prompt.md
new file mode 100644
index 0000000..11df062
--- /dev/null
+++ b/.github/prompts/write-docs.prompt.md
@@ -0,0 +1,75 @@
+---
+description: "Instructions for writing coding documentation"
+tools: ["search/codebase", "edit/editFiles", "web/fetch"]
+---
+
+<!-- Top-level section: Defines the documentation-writing task and the step-by-step workflow the assistant should follow. Techniques: imperative verbs, numbered list for clear sequencing, and explicit prompts to elicit scope, audience, and content. -->
+
+# Write Documentation
+
+You are an AI assistant. Your task is to help the user write clear, concise, and comprehensive documentation for their codebase.
+
+Follow the canonical workflow, templates, formatting, saving, and quality gates in `.github/instructions/docs.instructions.md` (see anchor `#documentation-process-flow`). Do not embed or restate templates in this prompt; reference the SSOT instead. Only include custom steps or templates if the user explicitly overrides the defaults.
+
+<!-- Guardrails: Establishes best practices and anti-patterns for content style and scope. Techniques: Do/Don't bullets to emphasize constraints, explicit avoidance of jargon and assumptions. -->
+
+## Do's and Don'ts
+
+- Do use clear and concise language.
+- Do include examples and code snippets.
+- Do organize the documentation logically.
+- Don't use jargon or technical terms without explanation.
+- Don't omit important information or details.
+- Don't use emojis or informal language.
+- Don't assume prior knowledge of the codebase by the reader.
+- Don't create overly lengthy documents; aim for brevity and clarity.
+
+<!-- Inputs section: Declares required parameters to collect from the user and how to map them into the process. Techniques: bold labels for salience and ${input:...} placeholders for parameterization. -->
+
+## Inputs
+
+- **Purpose and Scope**: `${input:PurposeAndScope}`
+- **Target Audience**: `${input:TargetAudience}`
+- **Key Features and Functionalities**: `${input:KeyFeatures}`
+- **Existing Documentation**: `${input:ExistingDocumentation}`
+
+If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide information for each missing item before proceeding with documentation generation.
+
+<!-- Template outline: Provides a default structure to ensure completeness and logical flow. Techniques: bulleted scaffold that doubles as a fallback when the user doesn’t specify a structure. -->
+
+## Documentation Structure
+
+Use the canonical structure from `.github/instructions/docs.instructions.md`. If the user specifies a different structure, note it and proceed while still applying the SSOT’s quality gates and saving rules.
+
+<!-- Style guide: Defines formatting, syntax, and output conventions to maximize readability and toolability. Techniques: prescriptive bullets, fenced code block example, image/link patterns, and explicit save-location/filename defaults. -->
+
+## Formatting Guidelines
+
+Follow the formatting and saving guidance in `.github/instructions/docs.instructions.md`. Default to `/docs/` and Markdown unless the user specifies otherwise. Do not duplicate formatting rules here.
+
+<!-- QA and handoff: Describes verification, user feedback, and finalization steps. Techniques: imperative checklist and confirmation gate before saving. -->
+
+## Review and Finalization
+
+Use the review and approval steps in `.github/instructions/docs.instructions.md` (process flow). Confirm with the user before finalizing and saving.
+
+<!-- Validation gate: Ensures missing, ambiguous, or conflicting inputs are resolved before proceeding; also defines defaulting behavior. Techniques: conditional prompts and references to earlier sections for defaults. -->
+
+## Input Validation
+
+If inputs are missing/ambiguous/conflicting, follow the input collection and validation rules in `.github/instructions/docs.instructions.md`.
+
+<!-- Special cases and tailoring: Covers variations in output format, audience, and future requests. Techniques: always-confirm rule and instruction to adjust style/format based on user preference. -->
+
+## Special Instructions
+
+- Always confirm with the user before finalizing and saving the documentation.
+- If the user requests changes or revisions, make them promptly and accurately.
+- If the user requests additional documentation in the future, follow the same process outlined above.
+- If the user requests documentation for a different codebase or project, ask for relevant information and follow the same process outlined above.
+- If the user requests documentation in a different format (e.g., HTML, PDF), ask for their preferences and adjust the formatting guidelines accordingly.
+- If the user requests documentation for a specific audience (e.g., end-users, stakeholders), tailor the content and language to suit that audience.
+
+If you can clearly identify any inputs from the conversation immediately prior to this, check with the user that you have understood those inputs correctly. Else, if you can't clearly identify any inputs from the conversation immediately prior to this, prompt the user for each input. Map their responses to the documentation inputs: purpose and scope, target audience, key features and functionalities, and existing documentation.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/write-ears-spec.prompt.md b/.github/prompts/write-ears-spec.prompt.md
new file mode 100644
index 0000000..cc9ebf6
--- /dev/null
+++ b/.github/prompts/write-ears-spec.prompt.md
@@ -0,0 +1,163 @@
+---
+agent: "agent"
+description: "Create a specification using the EARS format"
+tools:
+  [
+    "search/codebase",
+    "search/usages",
+    "search/changes",
+    "read/terminalSelection",
+    "read/terminalLastCommand",
+    "web/fetch",
+    "search/searchResults",
+    "web/githubRepo",
+    "todo",
+    "edit/editFiles",
+    "search",
+    "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection",
+    "execute/createAndRunTask", "execute/runTask", "read/getTaskOutput",
+  ]
+---
+
+<!-- Top-level section: Establishes the overall task for the assistant and the high-level interaction pattern. Emphasis techniques: imperative phrasing ("Guide"), numbered steps for clarity, and explicit prompts to ensure structured, concise inputs. -->
+
+# Create EARS Spec
+
+You are an AI assistant. Guide the user step-by-step to create clear, structured requirements using the EARS (Easy Approach to Requirements Syntax) method.
+
+1. Ask the user to define the product's goals, requirements, domain, and supporting information. Prompt for concise, specific answers.
+2. For each requirement, prompt the user for:
+
+- Pre-condition(s)
+- Trigger(s)
+- System name
+- System response
+
+3. Challenge the user's assumptions. Ask clarifying questions to uncover gaps, ambiguities, or hidden constraints.
+4. For each feature, prompt for both wanted and unwanted behaviors. Ensure the user specifies how the system should respond to exceptions or undesired events.
+
+<!-- Inputs section: Defines named placeholders that the assistant should solicit and map to EARS clauses. Emphasis techniques: bold labels, inline variable syntax (${input:...}) to signal parameterization, and explicit mapping guidance for validation. -->
+
+## Inputs
+
+- **Pre-conditions**: `${input:Pre-condition(s)}`
+- **Triggers**: `${input:Trigger(s)}`
+- **System name**: `${input:SystemName}`
+- **Response**: `${input:Response}`
+
+If you can clearly identify any inputs from the conversation immediately prior to this, check with the user that you have understood those inputs correctly. Else, if you can't clearly identify any inputs from the conversation immediately prior to this, prompt the user for each input. Map their responses to the EARS clauses: pre-condition, trigger, system name, and system response.
+
+<!-- Rules section: Constrains the format and completeness of each requirement and clarifies notation. Emphasis techniques: angle-bracket placeholders (<...>), bold to denote mandatory elements, and bulleted lists to enumerate constraints. -->
+
+## EARS notation and ruleset
+
+- In the notation that follows `<>` denotes a clause
+- `**bold**` clauses are mandatory
+- Normal font indicates optional clauses
+- Superscripts are used to map clauses between generic template and examples
+- Each requirement must have:
+  - Zero or many pre-conditions
+  - Zero or one trigger
+  - One system name
+  - One or many system responses
+
+<!-- Canonical template: Presents the core EARS sentence structure to be used when drafting requirements. Emphasis techniques: fenced code block for the template, and ordered clause naming to reinforce correct sequence. -->
+
+### Generic EARS syntax
+
+```markdown
+While <pre-conditions> when <trigger> the **<system-name>** shall **<system-response>**
+```
+
+Use the EARS syntax to structure each requirement. Combine the user's inputs in the correct order: pre-condition, trigger, system name, system response.
+
+Always order clauses as: pre-condition(s), trigger(s), system name, system response. Remind the user if their input does not follow this order.
+
+<!-- Workflow section: Outlines the iterative end-to-end process the assistant should follow to elicit, draft, review, and finalize requirements. Emphasis techniques: numbered steps and imperative verbs to define a repeatable routine. -->
+
+## Process for creating an EARS specification
+
+Begin by prompting for inputs. Draft requirements using EARS syntax. Review and challenge each requirement with clarifying questions. Add pairs for wanted/unwanted behaviors. Repeat until all requirements are clear and complete.
+
+1. Prompt for product goals, requirements, domain, and information
+2. For each requirement, prompt for pre-condition(s), trigger(s), system name, and system response
+3. Challenge and clarify each requirement
+4. Prompt for wanted and unwanted behavior pairs
+5. Refine and finalize requirements
+
+<!-- Visual aid: Provides a Mermaid diagram to reinforce the iterative nature of the process and show loop-backs. Emphasis techniques: diagrammatic flow and succinct stage labels. -->
+
+### Process Diagram
+
+```mermaid
+flowchart TD
+  A[Prompt for Inputs] --> B[Draft EARS Requirements]
+  B --> C[Challenge & Clarify]
+  C --> D[Add Wanted/Unwanted Pairs]
+  D --> E[Refine & Finalize]
+  C --> B
+```
+
+<!-- Dialogue guidance: Specifies conversational tactics for deeper elicitation and ambiguity reduction. Emphasis techniques: quoted question stems ("What if...?", "Why...?") and directive phrasing to ensure active prompting and validation. -->
+
+## User Interaction Process
+
+For each requirement, ask the user "What if...?" and "Why...?" to uncover missing details or edge cases. Encourage the user to be specific and thorough.
+
+Actively prompt the user for each clause. Help them structure requirements using EARS patterns. Review and clarify each requirement interactively.
+
+<!-- Examples hub: Collects pattern-based exemplars to illustrate different EARS variants and when to use them. Emphasis techniques: subheadings per pattern, fenced code blocks, and explicit meta-instructions ("Tell the user:") to explain context. -->
+
+## Examples
+
+<!-- Ubiquitous pattern example: Shows an unconditional requirement used when no state or event gating is needed. Emphasis techniques: minimal template in a fenced block and a plain-language explanation of applicability. -->
+
+### Ubiqitious example
+
+```markdown
+The **<system-name>** shall **<system-response>**
+```
+
+Tell the user: Ubiquitous requirements apply at all times, without conditions or triggers.
+
+<!-- State-driven pattern example: Demonstrates requirements that hold while a condition is true. Emphasis techniques: "While" clause in the fenced example and a concise usage note. -->
+
+### State-driven example
+
+```markdown
+While <pre-condition> the **<system-name>** shall **<system-response>**
+```
+
+Tell the user: State-driven requirements apply only while certain conditions are true.
+
+<!-- Event-driven pattern example: Captures behavior tied to a triggering event. Emphasis techniques: "When" clause in the fenced example and guidance on event specificity. -->
+
+### Event-driven example
+
+```markdown
+When <trigger> the **<system-name>** shall **<system-response>**
+```
+
+Tell the user: Event-driven requirements specify system behavior when a particular event occurs.
+
+<!-- Complex pattern example: Combines state and event to express precise control logic. Emphasis techniques: dual clauses in the fenced example and explanation of combined usage. -->
+
+### Complex example
+
+```markdown
+While <pre-condition>, when <trigger>, the **<system-name>** shall **<system-response>**
+```
+
+Tell the user: Complex requirements combine state and event conditions for precise control.
+
+<!-- Unwanted behaviour pattern example: Specifies expected handling of undesired events or exceptions. Emphasis techniques: "if/then" phrasing, fenced example, and explicit focus on negative paths. -->
+
+### Unwanted behaviour example
+
+```markdown
+While <pre-condition>, if <trigger>, then the **<system-name>** shall **<system-response>**
+```
+
+Tell the user: Unwanted behavior requirements specify how the system should respond to undesired events or states.
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/prompts/write-prd.prompt.md b/.github/prompts/write-prd.prompt.md
new file mode 100644
index 0000000..8e2f29f
--- /dev/null
+++ b/.github/prompts/write-prd.prompt.md
@@ -0,0 +1,133 @@
+---
+agent: "agent"
+description: "Create a Product Requirements Document (PRD) using the repository PRD template and structured guidance for both humans and automation."
+tools:
+  [
+    "search/codebase",
+    "search/usages",
+    "search/changes",
+    "edit/editFiles",
+    "web/fetch",
+    "search",
+    "search/searchResults",
+    "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection",
+    "todo",
+  ]
+---
+
+<!-- Top-level purpose: Define the PRD creation task and guardrails. Techniques: clear title, imperative voice, and branch/filename conventions to guide edits. -->
+
+# Create a Product Requirements Document (PRD)
+
+Create a PRD for `${input:FeatureTitle}` using the company PRD template and the guidance below. If you do not have enough information to author a useful PRD, ask the user for the missing inputs (see "Inputs" section).
+
+If you are working in a git workflow, create a branch named `prd/[brief-title-slug]` when making file changes.
+
+<!-- Inputs section: Declare required parameters to collect and map into the PRD template. Techniques: bold labels and ${input:...} placeholders for parameterization. -->
+
+## Inputs
+
+- **FeatureTitle**: `${input:FeatureTitle}`
+- **Summary / Problem Statement**: `${input:Problem}`
+- **Goals & Objectives**: `${input:Goals}`
+- **Stakeholders**: `${input:Stakeholders}`
+- **Specifications & Use Cases**: `${input:Specifications}`
+- **Functional Requirements (with priority Must/Should/Could)**: `${input:FunctionalRequirements}`
+- **Non-Functional Requirements**: `${input:NonFunctionalRequirements}`
+- **Acceptance Criteria / Success Metrics**: `${input:AcceptanceCriteria}`
+- **Timeline & Milestones**: `${input:Timeline}`
+- **Constraints & Assumptions**: `${input:Constraints}`
+- **Out of Scope**: `${input:OutOfScope}`
+- **Risks & Mitigations**: `${input:Risks}`
+- **Open Questions**: `${input:OpenQuestions}`
+- **References / Related Docs**: `${input:References}`
+
+<!-- Validation: Ensure critical inputs are present and measurable. Techniques: checklist and targeted questioning rules. -->
+
+## Input validation
+
+If any required input (FeatureTitle, Problem, Goals, Stakeholders, Specifications, Functional Requirements, Acceptance Criteria) is missing or ambiguous, prompt the user with a concise, specific question to obtain it before generating the PRD. Validate that:
+
+- Goals are measurable (or ask for measurable targets)
+- Functional requirements are prioritised (Must/Should/Could)
+- Acceptance criteria map back to measurable success metrics
+
+<!-- Output requirements: Style, structure, and content expectations to produce review-ready docs. -->
+
+## Requirements for the generated PRD
+
+- Use clear, unambiguous language suitable for product, design, and engineering readers
+- Follow the `docs/PRDs/prd-template.md` structure and include the same sections
+- Provide measurable objectives and success metrics; include at least 3 SMART metrics using the snippet at `.github/prompts/snippets/prd-success-metrics.snippet.md`
+- Mark requirements with priority tags (Must/Should/Could)
+- Include a short rollout/implementation notes section and suggested acceptance tests
+- Call out dependencies, constraints, and open questions explicitly
+- Keep the document scannable: short paragraphs, bullet lists, and tables where helpful
+
+<!-- Persistence: Where to save and how to name files for consistency and discoverability. -->
+
+## File naming & location
+
+Save the PRD to `/docs/PRDs/` using a filename that is a short slug of the feature title, e.g.: `prd-[brief-title-slug].md`. If there is an existing convention in the repo, follow it; otherwise use the filename pattern above.
+
+<!-- Canonical structure: Must mirror the repo PRD template. -->
+
+## Output structure
+
+The generated PRD must follow the PRD template in `docs/PRDs/prd-template.md` and include these sections (at minimum):
+
+- Revision History
+- Overview (Problem Statement, Value Proposition)
+- Goals & Objectives
+- Stakeholders
+- Specifications & Use Cases
+- Functional Requirements (with priorities)
+- Out of Scope
+- Non-Functional Requirements
+- Success Metrics (populate using `.github/prompts/snippets/prd-success-metrics.snippet.md`)
+- Constraints & Assumptions
+- Timeline & Milestones
+- Risks & Mitigations
+- Open Questions
+- References & Related Documents
+
+Where helpful, add short implementation notes and suggested acceptance tests that engineering and QA can run.
+
+<!-- Behavioral constraints: Interaction and scoping expectations for the assistant. -->
+
+## Behavioural expectations for the agent
+
+- If asked to create a PRD without sufficient inputs, ask only targeted clarifying questions (no more than 3 at a time).
+- Produce a first-draft PRD that is ready for product review and iteration; do not assume final approval.
+- When appropriate, suggest a minimal MVP scope and optional future enhancements.
+
+<!-- Example flow: A concise runbook for how to operate this prompt effectively. -->
+
+## Example minimal prompt flow
+
+1. Validate inputs; ask for any missing critical details
+2. Produce a headline summary and a one-paragraph problem statement
+3. Fill out the PRD sections following the template
+4. Add a short checklist of next steps (research, design, engineering spikes, stakeholders to consult)
+
+<!-- Notes: Implementation and git workflow guidance. -->
+
+## Notes
+
+- Use the `docs/PRDs/prd-template.md` as the canonical template. Ensure front matter or filename conventions used in this repo are followed.
+- If you save a file, prefer creating a branch and committing the file; if you cannot push, notify the user and provide exact git commands they can run locally.
+
+<PROCESS_REQUIREMENTS type="MANDATORY">
+
+- If essential inputs are missing or ambiguous, ask targeted questions (≤3 at a time) before drafting.
+- Follow the PRD template strictly; do not omit required sections.
+- Keep success metrics measurable; map acceptance criteria to goals.
+  </PROCESS_REQUIREMENTS>
+
+<CRITICAL_REQUIREMENT type="MANDATORY">
+
+- Save under `docs/PRDs/` using `prd-[brief-title-slug].md` unless an existing convention overrides it.
+- Do not publish without confirming with the requester or PRD owner.
+  </CRITICAL_REQUIREMENT>
+
+<!-- © Capgemini 2026 -->
diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml
new file mode 100644
index 0000000..f60793f
--- /dev/null
+++ b/.github/workflows/docs-lint.yml
@@ -0,0 +1,38 @@
+name: Docs Lint & Links
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          globs: |
+            **/*.md
+            !.github/**/*.md
+          config: .markdownlint.jsonc
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run lychee link checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: |
+            --config .lychee.toml \
+            --verbose \
+            **/*.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+# © Capgemini 2026
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
new file mode 100644
index 0000000..e1135d1
--- /dev/null
+++ b/.github/workflows/main.yml
@@ -0,0 +1,199 @@
+name: Build the File App
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  SONAR_PROJECT: ${{ github.event.repository.name }}
+  PASCAL_REPO_NAME: Will.Be.Set.By.Step
+  SOLUTION_FILE: Will.Be.Set.slnx
+  CONFIGURATION: Release
+  DOTNET_CORE_VERSION: 10.0.100
+  WORKING_DIRECTORY: src/
+permissions:
+  contents: read
+jobs:
+  test:
+    name: Run tests (matrix)
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    continue-on-error: ${{ matrix.os == 'macos-latest' }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ env.DOTNET_CORE_VERSION }}
+
+      - name: Cache NuGet packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.nuget/packages
+          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', '**/*.slnx') }}
+          restore-keys: |
+            ${{ runner.os }}-nuget-
+              
+      - name: PascalCase repo name with rules
+        run: |
+          raw="${{ github.event.repository.name }}"
+
+          # Split on '-' and PascalCase each segment, rejoin with '.'
+          pascal=$(echo "$raw" | awk -F'-' '{
+            OFS="."
+            for (i=1; i<=NF; i++) {
+              $i = toupper(substr($i,1,1)) substr($i,2)
+            }
+            print
+          }')
+
+          # Adjust leading Astar → AStar
+          pascal=$(echo "$pascal" | sed 's/^Astar/AStar/')
+
+          # Add suffix
+          pascal="${pascal}.slnx"
+
+          echo "PASCAL_REPO_NAME=$pascal" >> $GITHUB_ENV
+
+          echo "SOLUTION_FILE=$pascal" >> $GITHUB_ENV
+
+      - name: PASCAL_REPO_NAME
+        run: echo ${{ env.PASCAL_REPO_NAME }}
+
+      - name: SOLUTION_FILE
+        run: echo ${{ env.SOLUTION_FILE }}
+
+      - name: Restore ${{ env.PASCAL_REPO_NAME }}
+        run: dotnet restore ${{ env.PASCAL_REPO_NAME }}
+
+      - name: Build solution
+        run: dotnet build ${{ env.SOLUTION_FILE }} --configuration Release
+
+      - run: echo "REPO_NAME=${{ github.event.repository.name }}" >> $GITHUB_ENV
+
+      - name: Run unit tests and collect coverage (XPlat)
+        run: |
+          dotnet test --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory TestResults --filter "FullyQualifiedName!~Integration&FullyQualifiedName!~EndToEnd" ${{ env.SOLUTION_FILE }}.slnx
+
+      - name: Upload TestResults artifact (contains coverage)
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: testruns-${{ matrix.os }}
+          path: TestResults
+          retention-days: 30
+
+  sonar:
+    name: SonarCloud analysis and coverage
+    needs: [test, coverage-aggregate]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ env.DOTNET_CORE_VERSION }}
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: "zulu"
+
+      - name: 🛠 Cache SonarQube Cloud scanner
+        id: cache-sonar-scanner
+        uses: actions/cache@v4.2.3
+        with:
+          path: ./.sonar/scanner
+          key: ${{ runner.os }}-sonar-scanner
+          restore-keys: ${{ runner.os }}-sonar-scanner
+
+      - name: 🛠 Install SonarQube Cloud scanner
+        if: steps.cache-sonar-scanner.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p ./.sonar/scanner
+          dotnet tool update dotnet-sonarscanner --tool-path ./.sonar/scanner
+
+      - name: Download merged coverage
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-merged
+          path: ./coverage-merged
+
+      - name: Run SonarCloud analysis using merged Opencover
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: |
+          ./.sonar/scanner/dotnet-sonarscanner begin /k:"astar-development_${{ env.SONAR_PROJECT }}" /o:"astar-development" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.host.url="https://sonarcloud.io" /d:sonar.cs.opencover.reportsPaths=coverage-merged/Opencover.xml /d:sonar.scanner.scanAll=false
+          dotnet build --configuration Release
+          ./.sonar/scanner/dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
+
+  build:
+    needs: [test]
+    runs-on: windows-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    steps:
+      - name: Install .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ env.DOTNET_CORE_VERSION }}
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build solution
+        run: dotnet build --configuration Release
+
+  coverage-aggregate:
+    name: Aggregate coverage reports
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./artifacts
+
+      - name: Install ReportGenerator
+        run: dotnet tool install --global dotnet-reportgenerator-globaltool || true
+
+      - name: Merge reports and generate HTML + Cobertura + OpenCover
+        run: |
+          reportgenerator -reports:"artifacts/**/coverage.cobertura.xml" -targetdir:coverage-merged -reporttypes:"Html;Cobertura;Opencover"
+
+      - name: Upload merged coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-merged
+          path: coverage-merged
+          retention-days: 30
diff --git a/.github/workflows/policy-lint.yml b/.github/workflows/policy-lint.yml
new file mode 100644
index 0000000..1e6ce4a
--- /dev/null
+++ b/.github/workflows/policy-lint.yml
@@ -0,0 +1,27 @@
+name: Policy Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  
+jobs:
+  validate-policy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Run policy validator
+        run: |
+          node scripts/validate-policy.js
+
+# © Capgemini 2026
diff --git a/_repo-setup-scripts/configure-gh-repo.sh b/_repo-setup-scripts/configure-gh-repo.sh
new file mode 100755
index 0000000..0dd9ba3
--- /dev/null
+++ b/_repo-setup-scripts/configure-gh-repo.sh
@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+########################################
+# Config – toggle features here
+########################################
+
+ENABLE_AUTO_MERGE=true
+DELETE_BRANCH_ON_MERGE=true
+
+REQUIRE_PR_REVIEWS=true
+REQUIRED_APPROVING_REVIEWS=1
+REQUIRE_CODEOWNER_REVIEWS=false
+DISMISS_STALE_REVIEWS=true
+REQUIRE_LAST_PUSH_APPROVAL=false
+
+REQUIRE_STATUS_CHECKS=true
+STATUS_CHECKS_STRICT=true
+STATUS_CHECK_CONTEXTS=()  # e.g. ("ci/test" "ci/build")
+
+ENFORCE_ADMINS=true
+REQUIRE_LINEAR_HISTORY=true
+REQUIRE_CONVERSATION_RESOLUTION=true
+REQUIRE_SIGNED_COMMITS=true
+
+########################################
+# Helpers
+########################################
+
+log()   { printf '[INFO ] %s\n' "$*" >&2; }
+warn()  { printf '[WARN ] %s\n' "$*" >&2; }
+error() { printf '[ERROR] %s\n' "$*" >&2; }
+
+DRY_RUN=false
+ERRORS=()
+
+record_error() {
+  ERRORS+=("$1")
+  error "$1"
+}
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    error "Required command '$1' not found"
+    exit 1
+  }
+}
+
+resolve_repo() {
+  if [[ $# -ge 1 ]]; then
+    echo "$1"
+    return
+  fi
+
+  if gh_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null); then
+    echo "$gh_repo"
+    return
+  fi
+
+  error "Could not determine repository. Pass owner/repo or run inside a repo."
+  exit 1
+}
+
+########################################
+# Core request executor (real or dry-run)
+########################################
+
+send_request() {
+  local method=$1
+  local endpoint=$2
+  local body=$3
+
+  if $DRY_RUN; then
+    log "DRY RUN: $method $endpoint"
+    printf "%s\n\n" "$body"
+    return 0
+  fi
+
+  if ! gh api -X "$method" "$endpoint" \
+      -H "Accept: application/vnd.github+json" \
+      --input - <<<"$body"; then
+    return 1
+  fi
+}
+
+########################################
+# Payload builders
+########################################
+
+build_repo_settings_payload() {
+  cat <<EOF
+{
+  "allow_auto_merge": $ENABLE_AUTO_MERGE,
+  "delete_branch_on_merge": $DELETE_BRANCH_ON_MERGE
+}
+EOF
+}
+
+build_branch_protection_payload() {
+  local required_status_checks_json
+
+  if $REQUIRE_STATUS_CHECKS && ((${#STATUS_CHECK_CONTEXTS[@]} > 0)); then
+    local contexts_json
+    contexts_json="[\"$(printf '%s","' "${STATUS_CHECK_CONTEXTS[@]}" | sed 's/,"$//')\"]"
+
+    required_status_checks_json=$(cat <<JSON
+{
+  "strict": $STATUS_CHECKS_STRICT,
+  "contexts": $contexts_json
+}
+JSON
+)
+  else
+    if $REQUIRE_STATUS_CHECKS && ((${#STATUS_CHECK_CONTEXTS[@]} == 0)); then
+      warn "REQUIRE_STATUS_CHECKS=true but STATUS_CHECK_CONTEXTS is empty – disabling status checks in payload to avoid invalid combination."
+    fi
+    required_status_checks_json="null"
+  fi
+
+  cat <<EOF
+{
+  "required_status_checks": $required_status_checks_json,
+  "enforce_admins": $ENFORCE_ADMINS,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": $REQUIRED_APPROVING_REVIEWS,
+    "require_code_owner_reviews": $REQUIRE_CODEOWNER_REVIEWS,
+    "dismiss_stale_reviews": $DISMISS_STALE_REVIEWS,
+    "require_last_push_approval": $REQUIRE_LAST_PUSH_APPROVAL
+  },
+  "restrictions": null,
+  "required_linear_history": $REQUIRE_LINEAR_HISTORY,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "required_conversation_resolution": $REQUIRE_CONVERSATION_RESOLUTION
+}
+EOF
+}
+
+########################################
+# Operations
+########################################
+
+apply_repo_settings() {
+  local repo=$1
+  local payload
+  payload=$(build_repo_settings_payload)
+
+  log "Applying repo settings to $repo"
+
+  if ! send_request PATCH "repos/$repo" "$payload"; then
+    record_error "Failed to update repo settings for $repo"
+  fi
+}
+
+apply_branch_protection() {
+  local repo=$1
+  local branch="main"
+  local payload
+  payload=$(build_branch_protection_payload)
+
+  log "Applying branch protection to $repo ($branch)"
+
+  if ! send_request PUT "repos/$repo/branches/$branch/protection" "$payload"; then
+    record_error "Failed to update branch protection for $repo ($branch)"
+  fi
+}
+
+apply_signed_commits() {
+  local repo=$1
+  local branch="main"
+
+  if ! $REQUIRE_SIGNED_COMMITS; then
+    log "Signed commits disabled — skipping"
+    return
+  fi
+
+  log "Enabling required signed commits for $repo ($branch)"
+
+  if ! send_request POST "repos/$repo/branches/$branch/protection/required_signatures" "{}"; then
+    record_error "Failed to enable required signed commits for $repo ($branch)"
+  fi
+}
+
+########################################
+# Main
+########################################
+
+main() {
+  require_cmd gh
+
+  if [[ "${1:-}" == "--dry-run" ]]; then
+    DRY_RUN=true
+    shift
+    log "Dry-run mode enabled — no changes will be applied"
+  fi
+
+  local repo
+  repo=$(resolve_repo "$@")
+
+  log "Using repository: $repo"
+
+  apply_repo_settings "$repo"
+  apply_branch_protection "$repo"
+  apply_signed_commits "$repo"
+
+  if ((${#ERRORS[@]} > 0)); then
+    warn ""
+    warn "Completed with errors:"
+    for e in "${ERRORS[@]}"; do warn " - $e"; done
+    exit 1
+  fi
+
+  log "All operations completed successfully"
+}
+
+main "$@"
diff --git a/_repo-setup-scripts/log.txt b/_repo-setup-scripts/log.txt
new file mode 100644
index 0000000..c0e8f64
--- /dev/null
+++ b/_repo-setup-scripts/log.txt
@@ -0,0 +1 @@
+{"id":1178907516,"node_id":"R_kgDORkSzfA","name":"astar-dev-template","full_name":"astar-development/astar-dev-template","private":false,"owner":{"login":"astar-development","id":185268376,"node_id":"O_kgDOCwr4mA","avatar_url":"https://avatars.githubusercontent.com/u/185268376?v=4","gravatar_id":"","url":"https://api.github.com/users/astar-development","html_url":"https://github.com/astar-development","followers_url":"https://api.github.com/users/astar-development/followers","following_url":"https://api.github.com/users/astar-development/following{/other_user}","gists_url":"https://api.github.com/users/astar-development/gists{/gist_id}","starred_url":"https://api.github.com/users/astar-development/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/astar-development/subscriptions","organizations_url":"https://api.github.com/users/astar-development/orgs","repos_url":"https://api.github.com/users/astar-development/repos","events_url":"https://api.github.com/users/astar-development/events{/privacy}","received_events_url":"https://api.github.com/users/astar-development/received_events","type":"Organization","user_view_type":"public","site_admin":false},"html_url":"https://github.com/astar-development/astar-dev-template","description":"Thoughts on creating a template repo","fork":false,"url":"https://api.github.com/repos/astar-development/astar-dev-template","forks_url":"https://api.github.com/repos/astar-development/astar-dev-template/forks","keys_url":"https://api.github.com/repos/astar-development/astar-dev-template/keys{/key_id}","collaborators_url":"https://api.github.com/repos/astar-development/astar-dev-template/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/astar-development/astar-dev-template/teams","hooks_url":"https://api.github.com/repos/astar-development/astar-dev-template/hooks","issue_events_url":"https://api.github.com/repos/astar-development/astar-dev-template/issues/events{/number}","events_url":"https://api.github.com/repos/astar-development/astar-dev-template/events","assignees_url":"https://api.github.com/repos/astar-development/astar-dev-template/assignees{/user}","branches_url":"https://api.github.com/repos/astar-development/astar-dev-template/branches{/branch}","tags_url":"https://api.github.com/repos/astar-development/astar-dev-template/tags","blobs_url":"https://api.github.com/repos/astar-development/astar-dev-template/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/astar-development/astar-dev-template/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/astar-development/astar-dev-template/git/refs{/sha}","trees_url":"https://api.github.com/repos/astar-development/astar-dev-template/git/trees{/sha}","statuses_url":"https://api.github.com/repos/astar-development/astar-dev-template/statuses/{sha}","languages_url":"https://api.github.com/repos/astar-development/astar-dev-template/languages","stargazers_url":"https://api.github.com/repos/astar-development/astar-dev-template/stargazers","contributors_url":"https://api.github.com/repos/astar-development/astar-dev-template/contributors","subscribers_url":"https://api.github.com/repos/astar-development/astar-dev-template/subscribers","subscription_url":"https://api.github.com/repos/astar-development/astar-dev-template/subscription","commits_url":"https://api.github.com/repos/astar-development/astar-dev-template/commits{/sha}","git_commits_url":"https://api.github.com/repos/astar-development/astar-dev-template/git/commits{/sha}","comments_url":"https://api.github.com/repos/astar-development/astar-dev-template/comments{/number}","issue_comment_url":"https://api.github.com/repos/astar-development/astar-dev-template/issues/comments{/number}","contents_url":"https://api.github.com/repos/astar-development/astar-dev-template/contents/{+path}","compare_url":"https://api.github.com/repos/astar-development/astar-dev-template/compare/{base}...{head}","merges_url":"https://api.github.com/repos/astar-development/astar-dev-template/merges","archive_url":"https://api.github.com/repos/astar-development/astar-dev-template/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/astar-development/astar-dev-template/downloads","issues_url":"https://api.github.com/repos/astar-development/astar-dev-template/issues{/number}","pulls_url":"https://api.github.com/repos/astar-development/astar-dev-template/pulls{/number}","milestones_url":"https://api.github.com/repos/astar-development/astar-dev-template/milestones{/number}","notifications_url":"https://api.github.com/repos/astar-development/astar-dev-template/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/astar-development/astar-dev-template/labels{/name}","releases_url":"https://api.github.com/repos/astar-development/astar-dev-template/releases{/id}","deployments_url":"https://api.github.com/repos/astar-development/astar-dev-template/deployments","created_at":"2026-03-11T13:45:29Z","updated_at":"2026-03-11T13:45:35Z","pushed_at":"2026-03-11T13:45:30Z","git_url":"git://github.com/astar-development/astar-dev-template.git","ssh_url":"git@github.com:astar-development/astar-dev-template.git","clone_url":"https://github.com/astar-development/astar-dev-template.git","svn_url":"https://github.com/astar-development/astar-dev-template","homepage":null,"size":4,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"has_discussions":false,"forks_count":0,"mirror_url":null,"archived":false,"disabled":false,"open_issues_count":0,"license":{"key":"mit","name":"MIT License","spdx_id":"MIT","url":"https://api.github.com/licenses/mit","node_id":"MDc6TGljZW5zZTEz"},"allow_forking":true,"is_template":false,"web_commit_signoff_required":false,"has_pull_requests":true,"pull_request_creation_policy":"all","topics":[],"visibility":"public","forks":0,"open_issues":0,"watchers":0,"default_branch":"main","permissions":{"admin":true,"maintain":true,"push":true,"triage":true,"pull":true},"allow_squash_merge":true,"allow_merge_commit":true,"allow_rebase_merge":true,"allow_auto_merge":true,"delete_branch_on_merge":true,"allow_update_branch":false,"use_squash_pr_title_as_default":false,"squash_merge_commit_message":"COMMIT_MESSAGES","squash_merge_commit_title":"COMMIT_OR_PR_TITLE","merge_commit_message":"PR_TITLE","merge_commit_title":"MERGE_MESSAGE","custom_properties":{},"organization":{"login":"astar-development","id":185268376,"node_id":"O_kgDOCwr4mA","avatar_url":"https://avatars.githubusercontent.com/u/185268376?v=4","gravatar_id":"","url":"https://api.github.com/users/astar-development","html_url":"https://github.com/astar-development","followers_url":"https://api.github.com/users/astar-development/followers","following_url":"https://api.github.com/users/astar-development/following{/other_user}","gists_url":"https://api.github.com/users/astar-development/gists{/gist_id}","starred_url":"https://api.github.com/users/astar-development/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/astar-development/subscriptions","organizations_url":"https://api.github.com/users/astar-development/orgs","repos_url":"https://api.github.com/users/astar-development/repos","events_url":"https://api.github.com/users/astar-development/events{/privacy}","received_events_url":"https://api.github.com/users/astar-development/received_events","type":"Organization","user_view_type":"public","site_admin":false},"security_and_analysis":{"secret_scanning":{"status":"enabled"},"secret_scanning_push_protection":{"status":"enabled"},"dependabot_security_updates":{"status":"disabled"},"secret_scanning_non_provider_patterns":{"status":"disabled"},"secret_scanning_validity_checks":{"status":"disabled"}},"network_count":0,"subscribers_count":0}{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection","required_status_checks":{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/required_status_checks","strict":true,"contexts":[],"contexts_url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/required_status_checks/contexts","checks":[]},"required_pull_request_reviews":{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/required_pull_request_reviews","dismiss_stale_reviews":true,"require_code_owner_reviews":false,"require_last_push_approval":false,"required_approving_review_count":1},"required_signatures":{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/required_signatures","enabled":true},"enforce_admins":{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/enforce_admins","enabled":true},"required_linear_history":{"enabled":true},"allow_force_pushes":{"enabled":false},"allow_deletions":{"enabled":false},"block_creations":{"enabled":false},"required_conversation_resolution":{"enabled":true},"lock_branch":{"enabled":false},"allow_fork_syncing":{"enabled":false}}{"url":"https://api.github.com/repos/astar-development/astar-dev-template/branches/main/protection/required_signatures","enabled":true}
\ No newline at end of file
diff --git a/_repo-setup-scripts/usage-guide-for-configure-gh-repo..md b/_repo-setup-scripts/usage-guide-for-configure-gh-repo..md
new file mode 100644
index 0000000..9c0ea55
--- /dev/null
+++ b/_repo-setup-scripts/usage-guide-for-configure-gh-repo..md
@@ -0,0 +1,32 @@
+How to use
+
+# Before running: 
+
+```bash
+chmod +x configure-gh-repo.sh
+```
+
+Make sure you’re authenticated with gh auth login and have repo scope.
+
+# How to run:
+
+Run either:
+
+- Inside a cloned repo:
+
+```bash
+    ./configure-gh-repo.sh
+```
+- Or explicitly:
+
+```bash
+    ./configure-gh-repo.sh owner/repo
+```
+
+# Dry Run
+
+Whichever approach you decide to use for running this script, you can add:
+
+```bash
+ --dry-run
+```
\ No newline at end of file
diff --git a/docs/.gitkeep b/docs/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/docs/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/scripts/enforce-coverage.js b/scripts/enforce-coverage.js
new file mode 100644
index 0000000..dfad3e3
--- /dev/null
+++ b/scripts/enforce-coverage.js
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/*
+Simple coverage enforcement script.
+- Reads a JSON summary from stdin or a file (istanbul/nyc, jest --coverage, etc.)
+- Enforces global >= 90%
+- Enforces core modules >= 95% (by path includes /src/core or /core/)
+- Enforces integrations/adapters >= 85% (by path includes /adapters or /integrations/)
+- Enforces 100% for files matched as hot paths or error/security (by filename hints)
+Exit non-zero on failure with a readable summary.
+*/
+
+const fs = require('fs');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const params = { file: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--file' && args[i + 1]) {
+      params.file = args[i + 1];
+      i++;
+    }
+  }
+  return params;
+}
+
+function loadSummary(file) {
+  const input = file ? fs.readFileSync(file, 'utf8') : fs.readFileSync(0, 'utf8');
+  return JSON.parse(input);
+}
+
+function pct(n) { return Math.round(n * 10000) / 100; }
+
+function classifyFile(path) {
+  const p = path.toLowerCase();
+  if (p.includes('/core/') || p.includes('/src/core/')) return 'core';
+  if (p.includes('/adapters/') || p.includes('/integrations/')) return 'integration';
+  return 'other';
+}
+
+function isCritical(path) {
+  const p = path.toLowerCase();
+  return (
+    p.includes('hot') ||
+    p.includes('critical') ||
+    p.includes('auth') ||
+    p.includes('security') ||
+    p.includes('error') ||
+    p.includes('exception')
+  );
+}
+
+function check(summary) {
+  const metrics = summary.total || summary;
+  const globalLines = metrics.lines.pct || metrics.lines.covered / metrics.lines.total * 100;
+  const globalPass = globalLines >= 90;
+
+  const failures = [];
+  if (!globalPass) failures.push(`Global lines coverage ${pct(globalLines)}% < 90%`);
+
+  // Per-file checks if available
+  if (summary && typeof summary === 'object') {
+    for (const [file, m] of Object.entries(summary)) {
+      if (file === 'total' || !m || !m.lines) continue;
+      const filePct = m.lines.pct || (m.lines.covered / m.lines.total * 100);
+      const cls = classifyFile(file);
+      if (isCritical(file) && filePct < 100) {
+        failures.push(`Critical path not fully covered: ${file} ${pct(filePct)}% < 100%`);
+        continue;
+      }
+      if (cls === 'core' && filePct < 95) {
+        failures.push(`Core module below 95%: ${file} ${pct(filePct)}%`);
+      } else if (cls === 'integration' && filePct < 85) {
+        failures.push(`Integration below 85%: ${file} ${pct(filePct)}%`);
+      }
+    }
+  }
+
+  return failures;
+}
+
+function main() {
+  try {
+    const { file } = parseArgs();
+    const summary = loadSummary(file);
+    const failures = check(summary);
+    if (failures.length) {
+      console.error('Coverage enforcement failed:\n- ' + failures.join('\n- '));
+      process.exit(1);
+    }
+    console.log('Coverage enforcement passed.');
+  } catch (e) {
+    console.error('Error running coverage enforcement:', e.message);
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+// © Capgemini 2025
diff --git a/scripts/validate-policy.js b/scripts/validate-policy.js
new file mode 100644
index 0000000..0660a93
--- /dev/null
+++ b/scripts/validate-policy.js
@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/*
+Validates that `.github/copilot-instructions.md` contains required SSOT tags/sections.
+Checks:
+- Presence of XML-like tags: <CRITICAL_REQUIREMENT>, <WORKFLOW_ENFORCEMENT>, <NAMING_REQUIREMENTS>, <COMMIT_REQUIREMENTS>, <PROCESS_REQUIREMENTS>, <CODING_REQUIREMENTS>
+- Presence of anchor #quality-policy
+- Presence of key headings: Project Methodologies, Coding Standards
+Exit non-zero with a readable message if any check fails.
+*/
+
+const fs = require('fs');
+const path = require('path');
+
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+function main() {
+  const repoRoot = process.cwd();
+  const filePath = path.join(repoRoot, '.github', 'copilot-instructions.md');
+  if (!fs.existsSync(filePath)) fail(`File not found: ${filePath}`);
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  const requiredTags = [
+    '<CRITICAL_REQUIREMENT',
+    '<WORKFLOW_ENFORCEMENT',
+    '<NAMING_REQUIREMENTS',
+    '<COMMIT_REQUIREMENTS',
+    '<PROCESS_REQUIREMENTS',
+    '<CODING_REQUIREMENTS'
+  ];
+  const missingTags = requiredTags.filter(t => !content.includes(t));
+  if (missingTags.length) {
+    fail('Missing required tags: ' + missingTags.join(', '));
+  }
+
+  if (!content.includes('# Quality & Coverage Policy') && !content.includes('# Quality & Coverage Policy'.toLowerCase())) {
+    // Also allow anchor reference if heading case changes
+    if (!content.toLowerCase().includes('## quality & coverage policy') && !content.includes('#quality-policy')) {
+      fail('Missing Quality & Coverage Policy section or anchor (#quality-policy).');
+    }
+  }
+
+  const requiredHeadings = [
+    '## Project Methodologies',
+    '## Coding Standards'
+  ];
+  const missingHeadings = requiredHeadings.filter(h => !content.includes(h));
+  if (missingHeadings.length) {
+    fail('Missing required headings: ' + missingHeadings.join(', '));
+  }
+
+  console.log('Policy validation passed.');
+}
+
+if (require.main === module) {
+  main();
+}
+
+// © Capgemini 2025
diff --git a/src/.gitkeep b/src/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/src/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/tests/.gitkeep b/tests/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/tests/.gitkeep
@@ -0,0 +1 @@
+