feat: merge 001-filament-json

.dockerignore

@@ -0,0 +1,16 @@
+node_modules/
+vendor/
+.git/
+.env
+.env.*
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+public/build/
+public/hot/
+storage/debugbar/
+storage/*.key
+/references/
+.idea/
+.vscode/

.gemini/commands/speckit.analyze.toml

@@ -0,0 +1,188 @@
+description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+
+prompt = """
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+{{args}}
+"""

.gemini/commands/speckit.checklist.toml

@@ -0,0 +1,298 @@
+description = "Generate a custom checklist for the current feature based on user requirements."
+
+prompt = """
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+     - If file exists, append to existing file
+   - Number items sequentially starting from CHK001
+   - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
+"""

.gemini/commands/speckit.clarify.toml

@@ -0,0 +1,185 @@
+description = "Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec."
+
+prompt = """
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 10 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: {{args}}
+"""

.gemini/commands/speckit.constitution.toml

@@ -0,0 +1,86 @@
+description = "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
+
+prompt = """
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
+"""

.gemini/commands/speckit.implement.toml

@@ -0,0 +1,139 @@
+description = "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
+
+prompt = """
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+"""

.gemini/commands/speckit.plan.toml

@@ -0,0 +1,93 @@
+description = "Execute the implementation planning workflow using the plan template to generate design artifacts."
+
+prompt = """
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh gemini`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+"""

.gemini/commands/speckit.specify.toml

@@ -0,0 +1,262 @@
+description = "Create or update the feature specification from a natural language feature description."
+
+prompt = """
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+   a. First, fetch all remote branches to ensure we have the latest information:
+
+      ```bash
+      git fetch --all --prune
+      ```
+
+   b. Find the highest feature number across all sources for the short-name:
+      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+   c. Determine the next available number:
+      - Extract all numbers from all three sources
+      - Find the highest number N
+      - Use N+1 for the new branch number
+
+   d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "{{args}}"` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+   - Only match branches/directories with the exact short-name pattern
+   - If no existing branches/directories found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
+"""

.gemini/commands/speckit.tasks.toml

@@ -0,0 +1,141 @@
+description = "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
+
+prompt = """
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: {{args}}
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Endpoints/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each contract/endpoint → to the user story it serves
+   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+"""

.gemini/commands/speckit.taskstoissues.toml

@@ -0,0 +1,34 @@
+description = "Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts."
+
+prompt = """
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+"""

.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "general": {
+    "previewFeatures": false
+  }
+}

.npmignore

@@ -0,0 +1,8 @@
+dist/
+build/
+public/build/
+node_modules/
+*.log
+.env
+.env.*
+coverage/

.prettierignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+build/
+public/build/
+public/hot/
+coverage/
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+*.log
+.env
+.env.*

.specify/memory/constitution.md

@@ -1,175 +1,50 @@
-<!--
+# [PROJECT_NAME] Constitution
-SYNC IMPACT REPORT
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
-==================
-Version Change: [initial] → 1.0.0
-Constitutional Establishment: Initial ratification
-
-Principles Defined:
-- I. Safety-First Operations (Intune criticality)
-- II. Immutable Versioning (audit & rollback foundation)
-- III. Defensive Restore (preview, validation, explicit confirmation)
-- IV. Auditability (comprehensive logging)
-- V. Tenant-Aware Architecture (future multi-tenant foundation)
-- VI. Graph Abstraction (isolated, rate-limit-friendly)
-- VII. Spec-Driven Development (Spec Kit workflow)
-
-Sections Added:
-- Security & Permissions
-- Technology Stack
-- Governance
-
-Templates Status:
-✅ spec-template.md - Aligned (user stories, acceptance criteria match safety principles)
-✅ plan-template.md - Aligned (constitution check gate, technical context)
-✅ tasks-template.md - Aligned (user story organization, test-first guidance)
-✅ agent-file-template.md - No updates required
-✅ checklist-template.md - No updates required
-
-Runtime Guidance Files:
-✅ Agents.md - Primary guidance source, fully aligned
-✅ README.md - Standard Laravel boilerplate, no constitution conflicts
-
-Follow-up TODOs: None
-
-Commit Message Suggestion:
-docs: establish constitution v1.0.0 (initial ratification with 7 core principles)
--->
-
-# TenantPilot Constitution
 
 ## Core Principles
 
-### I. Safety-First Operations
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
 
-Every destructive or high-impact action involving Intune configurations MUST implement safety mechanisms:
+### [PRINCIPLE_2_NAME]
-- **Explicit confirmation UI** for restore, rollback, and destructive operations
+<!-- Example: II. CLI Interface -->
-- **Dry-run/preview modes** where technically feasible, showing clear change summaries before execution
+[PRINCIPLE_2_DESCRIPTION]
-- **Validation gates** detecting conflicts, incompatible states, or invalid inputs
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
-- **Audit log entries** for all critical operations (backup creation, restore execution, policy rollback)
 
-**Rationale**: Intune configurations are critical production assets. A single misconfigured policy can affect thousands of devices. Safety gates prevent operational accidents and provide recovery visibility.
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
 
-### II. Immutable Versioning
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
 
-Policy versions MUST be stored as immutable snapshots:
+### [PRINCIPLE_5_NAME]
-- **Full payload capture** in JSONB with metadata (who, when, source tenant, policy type)
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-- **No in-place modifications** to version records after creation
+[PRINCIPLE_5_DESCRIPTION]
-- **Queryable history** by policy, time range, and actor
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
-- **Diff capabilities** between any two versions (human-readable summary + structured JSON where feasible)
 
-**Rationale**: Immutable versions provide reliable rollback targets, accurate audit trails, and trustworthy diff outputs. Mutable history undermines auditability and introduces rollback risks.
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
 
-### III. Defensive Restore
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
 
-Restore operations MUST be defensive and transparent:
+## [SECTION_3_NAME]
-- **Preview/dry-run mode** showing what changes will be applied before execution
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
-- **Selective restore** allowing granular control over which items to restore
-- **Conflict detection** flagging existing resources that may be overwritten or incompatible
-- **Pre-execution summary** clearly communicating scope, risks, and affected resources
-- **Explicit confirmation** required before executing any restore
 
-**Rationale**: Restore operations can overwrite production configurations. Defensive workflows reduce risk of unintended changes and provide administrators with informed control.
+[SECTION_3_CONTENT]
-
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
-### IV. Auditability
-
-All critical operations MUST produce comprehensive audit logs:
-- **Scope**: backup creation, restore execution/attempts, policy rollback, policy version creation
-- **Content**: actor, timestamp, operation type, affected resources, outcome (success/failure/partial)
-- **Tenant-scoped**: logs MUST be queryable per tenant for multi-tenant future support
-- **RBAC-respecting**: log access follows same permission model as operational access
-- **High-level Graph logging**: log Graph API calls without exposing secrets or sensitive payloads
-
-**Rationale**: Audit trails enable compliance verification, incident investigation, and operational transparency. They are non-negotiable for enterprise configuration management.
-
-### V. Tenant-Aware Architecture
-
-Data models and business logic MUST be tenant-scoped from day one:
-- **Tenant entity** present in schema even if v1 deploys single-tenant
-- **Foreign key relationships** reference tenant_id where applicable
-- **Service layer logic** accepts tenant context explicitly
-- **Isolation enforcement** ensures no cross-tenant data leakage in queries or operations
-
-**Rationale**: TenantPilot v1 is single-tenant per deployment, but the architecture must support multi-tenant evolution. Retrofitting tenant isolation later is expensive and error-prone.
-
-### VI. Graph Abstraction
-
-Microsoft Graph integration MUST be isolated behind a dedicated abstraction layer:
-- **Domain services** depend on `GraphClient` interface, not raw Graph SDK
-- **Responsibilities**: auth token handling, rate-limit-friendly batching, standardized error mapping
-- **No direct Graph calls** in controllers, Filament resources, or domain logic
-- **Testability**: Graph layer must be mockable for integration tests
-
-**Rationale**: Graph API complexity (auth, rate limits, versioning, error handling) should not bleed into domain logic. Abstraction enables cleaner testing, easier SDK upgrades, and centralized rate limit management.
-
-### VII. Spec-Driven Development
-
-All features MUST follow the Spec Kit workflow:
-1. **Read** `.specify/constitution.md` (this document)
-2. **Create/update** `.specify/spec.md` defining user stories, acceptance criteria, and requirements
-3. **Produce** `.specify/plan.md` with technical design, structure decisions, and constitution check
-4. **Break down** into `.specify/tasks.md` organized by independently testable user stories
-5. **Implement** in small, reviewable PRs aligned with tasks
-
-**Non-negotiable constraints**:
-- **Constitution check** in plan.md MUST pass before implementation
-- **User stories** in spec.md MUST be prioritized and independently testable
-- **Requirements changes** during implementation MUST update spec/plan before continuing
-- **Tasks** MUST be organized by user story to enable incremental delivery
-
-**Rationale**: Spec Kit enforces thoughtful design, prevents scope drift, and maintains alignment between requirements, design, and implementation. It provides checkpoints for validation before costly implementation work.
-
-## Security & Permissions
-
-- **Least privilege**: Graph scopes and app permissions MUST request only necessary access
-- **Role-based access control**: Admin vs. read-only auditor roles (v1 baseline)
-- **No secrets in code**: Use Laravel encrypted storage or environment-based secret management
-- **Tenant identifier validation**: All Graph operations MUST validate tenant context
-- **Encrypted storage**: Sensitive fields (tokens, credentials) MUST use Laravel encryption where stored
-
-## Technology Stack
-
-**Core Stack**:
-- Backend: **Laravel** (latest stable)
-- Admin UI: **Filament** (v3+)
-- Database: **PostgreSQL** (via Sail locally, managed service in production)
-- Auth: **Microsoft Identity** (Entra ID/Azure AD integration)
-- External API: **Microsoft Graph** (Intune endpoints)
-
-**Development Environment**:
-- Local: **Laravel Sail** (Docker-based, PostgreSQL container)
-- Tooling: **Drizzle** for local PostgreSQL workflows (if configured)
-- Testing: **Pest** (PHPUnit-based)
-
-**Deployment**:
-- Repository: **Gitea** (self-hosted)
-- Deployment: **Dokploy** on VPS (container-based)
-- Environments: **Staging** (mandatory validation gate) → **Production**
-
-**Constraints**:
-- PHP: **PSR-12** conventions
-- Migrations: **Reversible**, validated on Staging before Production
-- JSONB storage: Use for raw Graph payloads, policy snapshots, backup items
-- Indexing: **GIN indexes** on JSONB fields requiring search/filter
 
 ## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
 
-This constitution supersedes all other development practices and guidelines. It defines the non-negotiable principles for TenantPilot development.
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
 
-**Amendment Process**:
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-- Amendments require documentation in this file with version bump rationale
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
-- Version follows **semantic versioning**:
-  - **MAJOR**: Backward-incompatible governance changes (principle removal/redefinition)
-  - **MINOR**: New principles added or materially expanded guidance
-  - **PATCH**: Clarifications, wording improvements, non-semantic refinements
-- Constitution changes MUST propagate to affected templates and guidance files
-- All templates in `.specify/templates/` MUST align with active principles
-
-**Compliance Enforcement**:
-- All specs MUST include a "Constitution Check" section in plan.md
-- All PRs MUST verify compliance with relevant principles
-- Violations MUST be justified in plan.md Complexity Tracking section
-- Runtime development guidance lives in `Agents.md`, which MUST align with this constitution
-
-**Ratification**: This constitution was established to formalize TenantPilot's architectural and operational principles based on v1 specification requirements and the Spec Kit workflow.
-
-**Version**: 1.0.0 | **Ratified**: 2025-12-10 | **Last Amended**: 2025-12-10

.specify/plan.md

@@ -5,11 +5,12 @@ # Implementation Plan: TenantPilot v1
 **Spec Source**: `.specify/spec.md` (scope/restore matrix unchanged)
 
 ## Summary
-TenantPilot v1 already delivers tenant-scoped Intune inventory, immutable backups, version history with diffs, defensive restore flows, tenant setup/permissions health, settings normalization/display, and Highlander enforcement. Remaining priority work is the delegated Intune RBAC onboarding wizard. All Graph calls stay behind the abstraction with audit logging; snapshots remain JSONB with safety gates for high-risk types (preview-only).
+TenantPilot v1 already delivers tenant-scoped Intune inventory, immutable backups, version history with diffs, defensive restore flows, tenant setup, permissions/health, settings normalization/display, and Highlander enforcement. Remaining priority work is the delegated Intune RBAC onboarding wizard (US7) and afterwards the Graph Contract Registry & Drift Guard (US8). All Graph calls stay behind the abstraction with audit logging; snapshots remain JSONB with safety gates (preview-only for high-risk types).
 
 ## Status Snapshot (tasks.md is source of truth)
-- **Done**: US1 inventory, US2 backups, US3 versions/diffs, US4 restore preview/exec, scope config, soft-deletes/housekeeping, Highlander single current tenant, tenant setup & verify (US6), permissions/health overview (US7), table ActionGroup UX, settings normalization/display (US1b), Dokploy/Sail runbooks.  
+- **Done**: US1 inventory, US2 backups, US3 versions/diffs, US4 restore preview/exec, scope config, soft-deletes/housekeeping, Highlander single current tenant, tenant setup & verify (US6), permissions/health overview (US6), table ActionGroup UX, settings normalization/display (US1b), Dokploy/Sail runbooks.  
-- **Next up**: US8 (formerly labeled “User Story 7” in spec) Intune RBAC onboarding wizard (delegated, synchronous Filament flow).
+- **Next up**: **US7** Intune RBAC onboarding wizard (delegated, synchronous Filament flow).  
+- **Upcoming**: **US8** Graph Contract Registry & Drift Guard (contract registry, type-family handling, verification command, fallback strategies).
 
 ## Technical Baseline
 - Laravel 12, Filament 4, PHP 8.4; Sail-first with PostgreSQL.  
@@ -25,29 +26,63 @@ ## Completed Workstreams (no new action needed)
 - **US3 Versions/Diffs (Phase 5)**: Version capture, timelines, human+JSON diffs, soft-deletes with audit.  
 - **US4 Restore (Phase 6)**: Preview, selective execution, conflict warnings, per-type restore level (enabled vs preview-only), PowerShell decode/encode respected, audit of outcomes.  
 - **US6 Tenant Setup & Highlander (Phases 8 & 12)**: Tenant CRUD/verify, INTUNE_TENANT_ID override, `is_current` unique enforcement, “Make current” action, block deactivated tenants.  
-- **US7 Permissions/Health (Phase 9)**: Required permissions list, compare/check service, Verify action updates status and audit, permissions panel in Tenant detail.  
+- **US6 Permissions/Health (Phase 9)**: Required permissions list, compare/check service, Verify action updates status and audit, permissions panel in Tenant detail.  
-- **US1b Settings Display (Phase 13)**: PolicyNormalizer + SnapshotValidator, warnings for malformed/@odata mismatches, normalized settings and pretty JSON on policy/version detail, list badges, README section.  
+- **US1b Settings Display (Phase 13)**: PolicyNormalizer + SnapshotValidator, warnings for malformed snapshots, normalized settings and pretty JSON on policy/version detail, list badges, README section.  
 - **Housekeeping/UX (Phases 10–12)**: Soft/force deletes for tenants/backups/versions/restore runs with guards; table actions in ActionGroup per UX guideline.  
 - **Ops (Phase 7)**: Sail runbook and Dokploy staging→prod guidance captured.
 
-## Next Up: US8 Intune RBAC Onboarding Wizard (delegated, synchronous)
+## Execution Plan: US7 Intune RBAC Onboarding Wizard (Phase 14)
-- Entry: Tenant detail ActionGroup “Setup Intune RBAC”; gated to active tenants with `app_client_id`.  
+
-- Flow: explain/preconditions (role/scope/group mode, least-privilege warning), delegated login, synchronous execution in Filament (no queue for grant), post-check via Verify + canary reads.
+- Objectives: deliver delegated, tenant-scoped wizard that safely converges the Intune RBAC state for the configured service principal; fully audited, idempotent, least-privilege by default.
-  - Canary reads (read-only): `GET /deviceManagement/deviceConfigurations?$top=1` and `GET /deviceManagement/deviceCompliancePolicies?$top=1` (and `GET /identity/conditionalAccess/policies?$top=1` only if CA is enabled for the tenant/scope).
+- Scope alignment: FR-023–FR-030, constitution (Safety-First, Auditability, Tenant-Aware, Graph Abstraction). No secret/token persistence; delegated tokens stay request-local and are not stored in DB/cache.
-- Execution steps (idempotent): resolve service principal; ensure/create security group; add SP member; create/update role assignment with chosen scope; log audit for start/login/group/member/assignment/verify.  
+- Design decisions:
-- Optional jobs/CLI limited to CHECK/REPORT only (no grant).  
+  - Service: `RbacOnboardingService` orchestrates steps using `GraphClientInterface`; reuse `RbacHealthService` for verification; all calls through abstraction with error mapping.
-- Tests: happy path, rerun idempotent, missing permissions error mapping, scope-limited warning.  
+- Data: use existing tenant RBAC columns (`rbac_group_id`, `rbac_group_name`, `rbac_role_assignment_id`, `rbac_role_key`, `rbac_scope_mode`, `rbac_scope_id`, status fields). No new entities; ensure casts + guards.
-- Documentation: add wizard behavior, audit expectations, and least-privilege guidance once implemented.
+- Audit: log start, delegated login outcome, group ensure, membership ensure, role assignment ensure/update, verify results. No payload logging; only IDs/status codes.
-- Operational note: After admin-consent or RBAC changes, force a fresh token acquisition (e.g., clear app token cache) before re-trying sync/backup/restore; Verify should run with a non-stale token.
+- Wizard flow (Filament, Tenant detail ActionGroup):
-- Note: This is **Intune RBAC** for the **Enterprise App (service principal)**. No “App roles” need to be added in the App Registration; Graph API permissions + Intune role assignment are separate concerns.
+  1) Preconditions/config step with review screen: show tenant/app info, required permissions, least-privilege warning; inputs for role (default Policy/Profile Manager; Intune Administrator shows warning), scope (global default; optional group picker), group mode (create default `TenantPilot-Intune-RBAC` vs pick existing security-enabled group). Summarize planned changes before proceeding.
+  2) Delegated auth step: initiate login; on failure stop with actionable message + audit; do not store token beyond request.
+  3) Execute (synchronous): resolve service principal by `app_client_id`; on missing SP stop with consent-required hint + audit reason `sp_not_found`; ensure/create security group (validate `securityEnabled=true`); ensure SP membership (idempotent “already exists” OK); ensure/create/patch Intune role assignment for chosen role/scope; persist discovered IDs on tenant for idempotency.
+  4) Post-verify: force fresh token acquisition; run canary reads (deviceConfigurations, deviceCompliancePolicies, conditionalAccess if enabled); update RBAC/permission health; surface warnings if scope-limited; audit verify result.
+  5) Summary: show IDs (group, role assignment), role/scope used, verify status, CTA to retry policy sync.
+- UX rules: action only for active tenants with `app_client_id`; keep in ActionGroup with Admin consent/Verify; show badge/hint if RBAC missing; warnings on selecting Intune Administrator role; block execution if tenant inactive or missing consent/SP.
+- Safety/idempotency: handle “already exists” as success; no self-heal jobs; retry-safe writes; no queue usage to avoid token expiry; timeouts surfaced clearly; no delegated token persistence.
+- Tests: happy path, rerun idempotent, SP missing, insufficient privileges, non-security-enabled group failure, scope-limited warning, delegated auth failure path; Filament wizard visibility + summary rendering; health prompts to run wizard when RBAC missing.
+- Documentation: add wizard behavior, least-privilege defaults, audit expectations, “no token storage”, and how to rerun safely; note CTA to retry policy sync.
+- Operational note: After admin-consent or RBAC changes, force a fresh token acquisition (e.g., clear app token cache) before re-trying sync/backup/restore; Verify should run with a non-stale token. Optional CHECK/REPORT jobs only (no grant) remain out-of-scope for this phase.
+- Testing plan (Pest):
+  - Service unit tests: happy path, rerun idempotent, SP missing, insufficient privileges, scope-limited warning, group exists/not security-enabled failure.
+  - Filament feature: wizard visibility gating, delegated failure path, successful run shows summary and updates health, warnings rendered.
+  - Health integration: Verify reflects RBAC status and prompts to run wizard when missing.
+- Deployment/ops: no new env vars; ensure migrations for tenant RBAC columns are applied; run targeted tests `php artisan test tests/Unit/RbacOnboardingServiceTest.php tests/Feature/Filament/TenantRbacWizardTest.php`; Pint on touched files.
+
+## Upcoming: US8 Graph Contract Registry & Drift Guard (Phase 15)
+
+- Objectives: centralize Graph contract assumptions per supported type/endpoint and provide drift detection + safe fallbacks so preview/restore remain stable on Graph shape/capability changes.
+- Scope alignment: FR-031–FR-034 (spec), constitution (Safety-First, Auditability, Graph Abstraction, Tenant-Aware).
+- Approach:
+  - Artifact: `config/graph_contracts.php` (or similar) with per-type contract data:
+    - resource paths (collection + single item)
+    - allowed `$select` / allowed `$expand`
+    - **type families / allowed `@odata.type` values**
+    - create/update methods, id field
+    - hydration strategy (member expansion vs follow-up fetch vs unavailable)
+  - Service: registry + checker; integrate with Graph client to enforce allowed capabilities and downgrade on capability errors (retry without expands/selects), recording warnings/audit entries.
+  - Type families: treat derived `@odata.type` values **within a declared family** as compatible (no `odata_mismatch`) for routing preview/restore.
+  - Verification: `php artisan graph:contract:check` (staging/CI) to probe endpoints and surface actionable diffs when Graph changes; opt-in/guarded for prod.
+  - Docs: explain registry format and update process when Graph changes.
+- Testing outline: unit for registry lookups/type-family matching/fallback selection; integration/Pest to simulate capability errors and ensure downgrade path + correct routing for derived types.
 
 ## Testing & Quality Gates
-- Continue using targeted Pest runs per change set; add/extend tests for US8 accordingly.  
+- Continue using targeted Pest runs per change set; add/extend tests for US7 wizard now, and for US8 contracts when implemented.  
 - Run Pint on touched files before finalizing.  
-- Maintain tenant isolation, audit logging, and restore safety gates; validate @odata.type and malformed snapshots prior to restore execution.
+- Maintain tenant isolation, audit logging, and restore safety gates; validate snapshot shape and type-family compatibility prior to restore execution.
-- Safety gate: `@odata.type` mismatches MUST block restore execution (preview may still show details + warnings), to prevent applying payloads to the wrong policy type/platform.
+
+### Restore Safety Gate
+- Restore execution MUST be blocked if a snapshot’s `@odata.type` is **outside** the declared **type family** for the target policy type (prevent cross-type/platform restores).
+- Restore preview MAY still render details + warnings for out-of-family snapshots, but MUST NOT offer an apply action.
 
 ## Coordination
-- Update `.specify/tasks.md` to reflect progress on remaining US8 tasks; no new entities or scope changes introduced here.  
+- Update `.specify/tasks.md` to reflect progress on US7 wizard and future US8 contract tasks; no new entities or scope changes introduced here.  
 - Stage validation required before production for any migration or restore-impacting change.  
-- Keep Graph integration behind abstraction; no secrets in logs; follow existing UX patterns (ActionGroup, warnings for risky ops).
+- Keep Graph integration behind abstraction; no secrets in logs; follow existing UX patterns (ActionGroup, warnings for risky ops).

.specify/research_t186.md

@@ -0,0 +1,46 @@
+# Research T186 — settings_apply capability verification
+
+Objective
+---------
+Verify whether the Microsoft Graph endpoint `deviceManagement/configurationPolicies/{id}/settings` accepts writes (POST/PUT) for applying Settings Catalog settings and document the exact request body shape and required `@odata.type` values.
+
+Context
+-------
+Logs show `PATCH` to the parent resource fails with `ModelValidationFailure: Cannot apply PATCH to navigation property 'settings'`. A fallback implemented in RestoreService attempts to `POST` to `.../{id}/settings` but tenant behavior is inconsistent (some tenants return `NotSupported`).
+
+Verification Steps
+------------------
+1. Choose a test tenant and service principal that reflect the production app permissions.
+2. Fetch a sample Settings Catalog policy:
+
+```http
+GET /deviceManagement/configurationPolicies/{id}
+```
+
+3. Fetch settings subresource:
+
+```http
+GET /deviceManagement/configurationPolicies/{id}/settings
+```
+
+4. Construct a minimal settings payload (single setting) including `settingInstance.@odata.type` and try POST:
+
+```http
+POST /deviceManagement/configurationPolicies/{id}/settings
+Content-Type: application/json
+
+[ { <setting object with settingInstance and @odata.type> } ]
+```
+
+5. If POST fails, record full response body and headers (request-id, client-request-id). Try alternative shapes (e.g. POST `{ "settings": [...] }`) and different methods (PUT) if documented.
+
+6. Capture any success responses and validate resulting settings in the portal or via subsequent GET.
+
+Deliverables
+------------
+- `research_t186.md` (this file) populated with observed request/response bodies and decision (A: supported — include exact body_shape; B: unsupported — document fallback and admin instructions).
+- If supported, proposed `config/graph_contracts.php` entry finalized and tests updated.
+
+Notes
+-----
+- Do not include secrets in this document. Paste only non-sensitive request/response metadata and request ids.

.specify/spec.md

@@ -57,6 +57,11 @@ ## Scope
       name: "Applications (Metadata only)"
       graph_resource: "deviceAppManagement/mobileApps"
       notes: "Backup nur von Metadaten/Zuweisungen (kein Binary-Download in v1)."
+    
+    - key: settingsCatalogPolicy
+      name: "Settings Catalog Policy"
+      graph_resource: "deviceManagement/configurationPolicies"
+      notes: "Intune Settings Catalog Policies liegen NICHT unter deviceConfigurations, sondern unter configurationPolicies. v1 behandelt sie als eigenen Typ."
 
   restore_matrix:
     deviceConfiguration:
@@ -112,6 +117,12 @@ ## Scope
       restore: enabled
       risk: high
       notes: "Security-relevante Einstellungen (z. B. Credential Guard); Preview + klare Konflikt-Warnungen nötig."
+    
+    settingsCatalogPolicy:
+      backup: full
+      restore: enableds
+      risk: medium
+      notes: "Settings Catalog Policies sind Standard-Config-Policies (Settings Catalog). Preview/Audit Pflicht; Restore automatisierbar."
 
     mobileApp:
       backup: metadata-only
@@ -134,7 +145,7 @@ ### User Story 1 - Policy inventory listing (Priority: P1)
 
 1. **Given** an authenticated admin, **When** they open the Policies list, **Then** they see supported object types with identifiers, type/category, platform, and last-updated metadata.
 2. **Given** filtering by type/category, **When** the admin selects a type, **Then** only matching objects appear and the view remains tenant-scoped.
-
+3. **Given** Settings Catalog Policies exist in Intune, **When** the admin opens the Policies list and syncs, **Then** Settings Catalog Policies are listed as type `Settings Catalog Policy` (settingsCatalogPolicy) and are not mixed into `Device Configuration`.
 ---
 ### User Story 1b - Policy detail shows readable settings (Priority: P1)
 
@@ -264,6 +275,43 @@ ### User Story 6 - Berechtigungsübersicht & Health-Status (Priority: P1)
 1. **Given** a fresh checkout, **When** Sail commands run (`./vendor/bin/sail up -d`, `./vendor/bin/sail artisan migrate`), **Then** the app boots with PostgreSQL and Filament admin available.
 2. **Given** a pending release, **When** migrations and restore flows are validated on staging, **Then** production deployment proceeds with documented steps and environment parity.
 
+  ### User Story 8 – Graph Contract Registry & Drift Guard (Priority: P1)
+Admin soll sich darauf verlassen können, dass Backup/Restore/Preview nicht wegen Graph-Shape-Details (derived @odata.type, verbotene $expand/$select, Property-Abweichungen) “random” bricht.
+
+Acceptance Scenarios:
+	1.	Given ein Backup enthält @odata.type = #microsoft.graph.windows10CompliancePolicy,
+When Preview/Restore läuft,
+Then wird das als gültiger deviceCompliancePolicy-Family Typ behandelt (kein odata_mismatch), und der korrekte Endpoint/Method wird genutzt.
+	2.	Given ein Endpoint erlaubt bestimmte Expands/Selects nicht,
+When TenantPilot Requests baut,
+Then werden nur “allowed capabilities” verwendet (kein 400 durch OData parsing).
+	3.	Given Microsoft/Intune ändert Shape/Capabilities,
+When graph:contract:check läuft,
+Then schlägt der Check kontrolliert fehl und zeigt welcher Contract angepasst werden muss (statt dass Prod-Flows brechen).
+
+2) Neue Functional Requirements (FR-03x) ergänzen
+
+Beispiel, passend zu deinem Stil:
+	•	FR-031: System MUST maintain a central Graph Contract Registry per supported type/endpoint (resource path, allowed $select, allowed $expand, “type family” / allowed @odata.type values, create/update methods).
+	•	FR-032: Restore/Preview MUST treat derived @odata.type values as compatible within a declared type family (e.g. compliance policy family), and MUST NOT hard-fail on base-vs-derived mismatches.
+	•	FR-033: System MUST provide a verification command (e.g. php artisan graph:contract:check) that validates registry assumptions against live Graph behavior (at least via canary calls / lightweight probes), logging actionable diffs.
+	•	FR-034: When Graph returns capability errors (OData select/expand, unsupported features), system MUST downgrade to a safe fallback strategy (e.g. “no expand, extra fetches”) and MUST record a warning/audit entry.
+
+(Du kannst FR-033 “live check” auch optional machen für prod, aber mindestens in CI/Staging wertvoll.)
+
+3) Implementation Notes / Data Artefacts ergänzen
+
+Ein kleines, versioniertes Artefakt einführen, z. B.:
+	•	config/graph_contracts.php oder .specify/contracts/graph.yaml
+
+Darin pro Objekt-Typ:
+	•	resource (collection + single-item path)
+	•	type_family (Liste erlaubter @odata.type)
+	•	allowed_select / allowed_expand
+	•	member_hydration_strategy (z. B. “property array” vs “subresource” vs “not available”)
+	•	create_method / update_method / id_field
+
+Das verhindert “Wissens-Leaks” quer durch Services.
 ### Edge Cases
 
 - Graph permissions missing or expired, causing policy fetch/restore failures with clear error mapping and audit entries.

GEMINI.md

@@ -0,0 +1,671 @@
+# TenantPilot - Agent Guidelines
+
+## Context
+TenantPilot is an Intune Management application built with **Laravel** and **Filament**.
+It re-implements and extends key features inspired by the IntuneManagement project,
+with a focus on admin productivity, safe change management, and auditability.
+
+This repo uses GitHub Spec Kit.
+Primary spec artifacts live in `.specify/`.
+
+**Sail-first for local development. Dokploy-first for staging/production.**
+
+## Product Goals
+- Provide **Intune policy version control** (diff, history, rollback).
+- Enable reliable **backup and restore** of Intune configurations.
+- Extend Intune with **admin-focused features** that improve visibility, safety, and velocity.
+- Prioritize **auditability**, **least privilege**, and predictable operations.
+
+## Scope Reference
+When designing or implementing features, align with:
+- Policy inventory & metadata normalization
+- Change tracking and version snapshots
+- Safe restore flows (dry-run, validation, partial restore)
+- Reporting, dashboards, and operational insights
+- Tenant-scoped RBAC and audit logs
+
+## Workflow (Spec Kit)
+1. Read `.specify/constitution.md`
+2. For new work: create/update `.specify/spec.md`
+3. Produce `.specify/plan.md`
+4. Break into `.specify/tasks.md`
+5. Implement changes in small PRs
+
+If requirements change during implementation, update spec/plan before continuing.
+
+## Architecture Assumptions
+- Backend: Laravel (latest stable)
+- Admin UI: Filament
+- Auth: Microsoft identity integration (Entra ID/Azure AD) when applicable
+- External API: Microsoft Graph for Intune
+
+Do not assume additional services unless stated in spec.
+
+---
+
+## DevOps & Environments
+
+### Local Development
+- Local dev & testing use **Laravel Sail** (Docker).
+- Prefer Sail commands when referencing setup or running tests.
+- PostgreSQL is used locally via Sail.
+- **Drizzle** is used locally for PostgreSQL tooling (e.g., schema inspection, dev workflows)
+  **if configured in the repo**.
+
+### Repository
+- Repository is hosted on **Gitea**.
+- Do not assume GitHub-specific features (Actions, GH-specific PR automation)
+  unless explicitly added.
+- CI suggestions should be compatible with Gitea pipelines or external CI runners.
+
+### Deployment
+- Deployed via **Dokploy** on a **VPS**.
+- Two environments:
+  - **Staging**
+  - **Production**
+- Assume container-based deployments.
+- Changes that affect runtime must consider:
+  - environment variables
+  - database migrations
+  - queue/cron workers
+  - storage persistence/volumes
+  - reverse proxy/SSL likely handled by Dokploy
+
+### Release & Promotion Rules
+- Staging is the mandatory validation gate for Production.
+- Prefer:
+  - feature flags for risky admin operations
+  - staged rollout for backup/restore/versioning changes
+- Schema changes must be validated on Staging before Production.
+
+### Release Safety
+- For schema changes:
+  - provide safe, incremental migrations
+  - avoid long locks
+  - document rollback/forward steps
+- For Intune-critical flows:
+  - prefer dry-run/preview
+  - require explicit confirmation
+  - ensure audit logs
+
+---
+
+## Data Layer
+- Database: **PostgreSQL**
+- Prefer **JSONB** to store raw Graph policy snapshots and backup payloads.
+- Add appropriate indexes (e.g., **GIN** on JSONB where search/filter is expected).
+- Migrations must be reversible where possible.
+
+## Versioning Storage Strategy
+- Store **immutable** policy snapshots.
+- Track metadata separately (tenant, policy type, platform, created_by, created_at).
+- Prefer **full snapshots first** for correctness and simplicity.
+- Consider retention policies to prevent unbounded growth.
+
+---
+
+## Engineering Rules
+- PHP: follow PSR-12 conventions.
+- Prefer Laravel best practices (Service classes, Jobs, Events, Policies).
+- Keep Microsoft Graph integration isolated behind a dedicated abstraction layer.
+- Use dependency injection and clear interfaces for Graph clients.
+- No breaking changes to data structures or API contracts without updating:
+  - `.specify/spec.md`
+  - migration notes
+  - upgrade steps
+- If a TypeScript/JS tooling package exists, use strict typing rules there too.
+
+## Intune Data & Safety Rules
+- Treat Intune resources as **critical configuration**.
+- Every destructive action must support:
+  - explicit confirmation UI
+  - audit log entry
+  - optional dry-run/preview mode if feasible
+- Restore must be defensive:
+  - validate inputs
+  - detect conflicts
+  - allow selective restore
+  - show a clear pre-execution summary
+
+## Version Control Semantics
+- A "version" should be reproducible and queryable:
+  - what changed
+  - when
+  - by whom
+  - source tenant/environment
+- Provide diff outputs where possible:
+  - human-readable summary
+  - structured diff (JSON)
+
+## Observability & Audit
+- Log Graph calls at a high-level (no secrets).
+- Maintain an audit trail for:
+  - backups created
+  - restores executed/attempted
+  - policy changes detected/imported
+- Ensure logs are tenant-scoped and RBAC-respecting.
+
+## Security
+- Enforce least privilege.
+- Never store secrets in config or code.
+- Use Laravel encrypted storage or secure secret management where applicable.
+- Validate all tenant identifiers and Graph scopes.
+
+---
+
+## Commands
+
+### Sail (preferred locally)
+- `./vendor/bin/sail up -d`
+- `./vendor/bin/sail down`
+- `./vendor/bin/sail composer install`
+- `./vendor/bin/sail artisan migrate`
+- `./vendor/bin/sail artisan test`
+- `./vendor/bin/sail artisan` (general)
+
+### Drizzle (local DB tooling, if configured)
+- Use only for local/dev workflows.
+- Prefer running via package scripts, e.g.:
+  - `pnpm drizzle:generate`
+  - `pnpm drizzle:migrate`
+  - `pnpm drizzle:studio`
+
+(Agents should confirm the exact script names in `package.json` before suggesting them.)
+
+### Non-Docker fallback (only if needed)
+- `composer install`
+- `php artisan serve`
+- `php artisan migrate`
+- `php artisan test`
+
+### Frontend/assets/tooling (if present)
+- `pnpm install`
+- `pnpm dev`
+- `pnpm test`
+- `pnpm lint`
+
+---
+
+## Where to look first
+- `.specify/`
+- `AGENTS.md`
+- `README.md`
+- `app/`
+- `database/`
+- `routes/`
+- `resources/`
+- `config/`
+
+---
+
+## Definition of Done
+- Spec + Plan + Tasks aligned with implementation.
+- Tests added/updated.
+- UI includes clear admin-safe affordances for backup/restore/versioning.
+- Audit logging implemented for sensitive flows.
+- Documentation updated (README or in-app help).
+- Deployment impact assessed for:
+  - Staging
+  - Production
+  - migrations, env vars, queues
+
+---
+
+## AI Usage Note
+All AI agents must read:
+- `AGENTS.md`
+- `.specify/*`
+
+before proposing or implementing changes.
+
+## Reference Materials
+- PowerShell scripts from IntuneManagement are stored under `/references/IntuneManagement-master`
+  for implementation guidance only.
+- They must not be treated as production runtime dependencies.
+
+===
+
+<laravel-boost-guidelines>
+=== foundation rules ===
+
+# Laravel Boost Guidelines
+
+The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.
+
+## Foundational Context
+This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.
+
+- php - 8.4.15
+- filament/filament (FILAMENT) - v4
+- laravel/framework (LARAVEL) - v12
+- laravel/prompts (PROMPTS) - v0
+- livewire/livewire (LIVEWIRE) - v3
+- laravel/mcp (MCP) - v0
+- laravel/pint (PINT) - v1
+- laravel/sail (SAIL) - v1
+- pestphp/pest (PEST) - v4
+- phpunit/phpunit (PHPUNIT) - v12
+- tailwindcss (TAILWINDCSS) - v4
+
+## Conventions
+- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, naming.
+- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
+- Check for existing components to reuse before writing a new one.
+
+## Verification Scripts
+- Do not create verification scripts or tinker when tests cover that functionality and prove it works. Unit and feature tests are more important.
+
+## Application Structure & Architecture
+- Stick to existing directory structure - don't create new base folders without approval.
+- Do not change the application's dependencies without approval.
+
+## Frontend Bundling
+- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.
+
+## Replies
+- Be concise in your explanations - focus on what's important rather than explaining obvious details.
+
+## Documentation Files
+- You must only create documentation files if explicitly requested by the user.
+
+
+=== boost rules ===
+
+## Laravel Boost
+- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them.
+
+## Artisan
+- Use the `list-artisan-commands` tool when you need to call an Artisan command to double check the available parameters.
+
+## URLs
+- Whenever you share a project URL with the user you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain / IP, and port.
+
+## Tinker / Debugging
+- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly.
+- Use the `database-query` tool when you only need to read from the database.
+
+## Reading Browser Logs With the `browser-logs` Tool
+- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost.
+- Only recent browser logs will be useful - ignore old logs.
+
+## Searching Documentation (Critically Important)
+- Boost comes with a powerful `search-docs` tool you should use before any other approaches. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation specific for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages.
+- The 'search-docs' tool is perfect for all Laravel related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc.
+- You must use this tool to search for Laravel-ecosystem documentation before falling back to other approaches.
+- Search the documentation before making code changes to ensure we are taking the correct approach.
+- Use multiple, broad, simple, topic based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`.
+- Do not add package names to queries - package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`.
+
+### Available Search Syntax
+- You can and should pass multiple queries at once. The most relevant results will be returned first.
+
+1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'
+2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit"
+3. Quoted Phrases (Exact Position) - query="infinite scroll" - Words must be adjacent and in that order
+4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit"
+5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms
+
+
+=== php rules ===
+
+## PHP
+
+- Always use curly braces for control structures, even if it has one line.
+
+### Constructors
+- Use PHP 8 constructor property promotion in `__construct()`.
+    - <code-snippet>public function __construct(public GitHub $github) { }</code-snippet>
+- Do not allow empty `__construct()` methods with zero parameters.
+
+### Type Declarations
+- Always use explicit return type declarations for methods and functions.
+- Use appropriate PHP type hints for method parameters.
+
+<code-snippet name="Explicit Return Types and Method Params" lang="php">
+protected function isAccessible(User $user, ?string $path = null): bool
+{
+    ...
+}
+</code-snippet>
+
+## Comments
+- Prefer PHPDoc blocks over comments. Never use comments within the code itself unless there is something _very_ complex going on.
+
+## PHPDoc Blocks
+- Add useful array shape type definitions for arrays when appropriate.
+
+## Enums
+- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`.
+
+
+=== tests rules ===
+
+## Test Enforcement
+
+- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
+- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test` with a specific filename or filter.
+
+
+=== laravel/core rules ===
+
+## Do Things the Laravel Way
+
+- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
+- If you're creating a generic PHP class, use `php artisan make:class`.
+- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
+
+### Database
+- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
+- Use Eloquent models and relationships before suggesting raw database queries
+- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
+- Generate code that prevents N+1 query problems by using eager loading.
+- Use Laravel's query builder for very complex database operations.
+
+### Model Creation
+- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`.
+
+### APIs & Eloquent Resources
+- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.
+
+### Controllers & Validation
+- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
+- Check sibling Form Requests to see if the application uses array or string based validation rules.
+
+### Queues
+- Use queued jobs for time-consuming operations with the `ShouldQueue` interface.
+
+### Authentication & Authorization
+- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.).
+
+### URL Generation
+- When generating links to other pages, prefer named routes and the `route()` function.
+
+### Configuration
+- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`.
+
+### Testing
+- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
+- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
+- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
+
+### Vite Error
+- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.
+
+
+=== laravel/v12 rules ===
+
+## Laravel 12
+
+- Use the `search-docs` tool to get version specific documentation.
+- Since Laravel 11, Laravel has a new streamlined file structure which this project uses.
+
+### Laravel 12 Structure
+- No middleware files in `app/Http/Middleware/`.
+- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files.
+- `bootstrap/providers.php` contains application specific service providers.
+- **No app\Console\Kernel.php** - use `bootstrap/app.php` or `routes/console.php` for console configuration.
+- **Commands auto-register** - files in `app/Console/Commands/` are automatically available and do not require manual registration.
+
+### Database
+- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
+- Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
+
+### Models
+- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.
+
+
+=== livewire/core rules ===
+
+## Livewire Core
+- Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests.
+- Use the `php artisan make:livewire [Posts\CreatePost]` artisan command to create new components
+- State should live on the server, with the UI reflecting it.
+- All Livewire requests hit the Laravel backend, they're like regular HTTP requests. Always validate form data, and run authorization checks in Livewire actions.
+
+## Livewire Best Practices
+- Livewire components require a single root element.
+- Use `wire:loading` and `wire:dirty` for delightful loading states.
+- Add `wire:key` in loops:
+
+    ```blade
+    @foreach ($items as $item)
+        <div wire:key="item-{{ $item->id }}">
+            {{ $item->name }}
+        </div>
+    @endforeach
+    ```
+
+- Prefer lifecycle hooks like `mount()`, `updatedFoo()` for initialization and reactive side effects:
+
+<code-snippet name="Lifecycle hook examples" lang="php">
+    public function mount(User $user) { $this->user = $user; }
+    public function updatedSearch() { $this->resetPage(); }
+</code-snippet>
+
+
+## Testing Livewire
+
+<code-snippet name="Example Livewire component test" lang="php">
+    Livewire::test(Counter::class)
+        ->assertSet('count', 0)
+        ->call('increment')
+        ->assertSet('count', 1)
+        ->assertSee(1)
+        ->assertStatus(200);
+</code-snippet>
+
+
+    <code-snippet name="Testing a Livewire component exists within a page" lang="php">
+        $this->get('/posts/create')
+        ->assertSeeLivewire(CreatePost::class);
+    </code-snippet>
+
+
+=== livewire/v3 rules ===
+
+## Livewire 3
+
+### Key Changes From Livewire 2
+- These things changed in Livewire 2, but may not have been updated in this application. Verify this application's setup to ensure you conform with application conventions.
+    - Use `wire:model.live` for real-time updates, `wire:model` is now deferred by default.
+    - Components now use the `App\Livewire` namespace (not `App\Http\Livewire`).
+    - Use `$this->dispatch()` to dispatch events (not `emit` or `dispatchBrowserEvent`).
+    - Use the `components.layouts.app` view as the typical layout path (not `layouts.app`).
+
+### New Directives
+- `wire:show`, `wire:transition`, `wire:cloak`, `wire:offline`, `wire:target` are available for use. Use the documentation to find usage examples.
+
+### Alpine
+- Alpine is now included with Livewire, don't manually include Alpine.js.
+- Plugins included with Alpine: persist, intersect, collapse, and focus.
+
+### Lifecycle Hooks
+- You can listen for `livewire:init` to hook into Livewire initialization, and `fail.status === 419` for the page expiring:
+
+<code-snippet name="livewire:load example" lang="js">
+document.addEventListener('livewire:init', function () {
+    Livewire.hook('request', ({ fail }) => {
+        if (fail && fail.status === 419) {
+            alert('Your session expired');
+        }
+    });
+
+    Livewire.hook('message.failed', (message, component) => {
+        console.error(message);
+    });
+});
+</code-snippet>
+
+
+=== pint/core rules ===
+
+## Laravel Pint Code Formatter
+
+- You must run `vendor/bin/pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
+- Do not run `vendor/bin/pint --test`, simply run `vendor/bin/pint` to fix any formatting issues.
+
+
+=== pest/core rules ===
+
+## Pest
+### Testing
+- If you need to verify a feature is working, write or update a Unit / Feature test.
+
+### Pest Tests
+- All tests must be written using Pest. Use `php artisan make:test --pest {name}`.
+- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files - these are core to the application.
+- Tests should test all of the happy paths, failure paths, and weird paths.
+- Tests live in the `tests/Feature` and `tests/Unit` directories.
+- Pest tests look and behave like this:
+<code-snippet name="Basic Pest Test Example" lang="php">
+it('is true', function () {
+    expect(true)->toBeTrue();
+});
+</code-snippet>
+
+### Running Tests
+- Run the minimal number of tests using an appropriate filter before finalizing code edits.
+- To run all tests: `php artisan test`.
+- To run all tests in a file: `php artisan test tests/Feature/ExampleTest.php`.
+- To filter on a particular test name: `php artisan test --filter=testName` (recommended after making a change to a related file).
+- When the tests relating to your changes are passing, ask the user if they would like to run the entire test suite to ensure everything is still passing.
+
+### Pest Assertions
+- When asserting status codes on a response, use the specific method like `assertForbidden` and `assertNotFound` instead of using `assertStatus(403)` or similar, e.g.:
+<code-snippet name="Pest Example Asserting postJson Response" lang="php">
+it('returns all', function () {
+    $response = $this->postJson('/api/docs', []);
+
+    $response->assertSuccessful();
+});
+</code-snippet>
+
+### Mocking
+- Mocking can be very helpful when appropriate.
+- When mocking, you can use the `Pest\Laravel\mock` Pest function, but always import it via `use function Pest\Laravel\mock;` before using it. Alternatively, you can use `$this->mock()` if existing tests do.
+- You can also create partial mocks using the same import or self method.
+
+### Datasets
+- Use datasets in Pest to simplify tests which have a lot of duplicated data. This is often the case when testing validation rules, so consider going with this solution when writing tests for validation rules.
+
+<code-snippet name="Pest Dataset Example" lang="php">
+it('has emails', function (string $email) {
+    expect($email)->not->toBeEmpty();
+})->with([
+    'james' => 'james@laravel.com',
+    'taylor' => 'taylor@laravel.com',
+]);
+</code-snippet>
+
+
+=== pest/v4 rules ===
+
+## Pest 4
+
+- Pest v4 is a huge upgrade to Pest and offers: browser testing, smoke testing, visual regression testing, test sharding, and faster type coverage.
+- Browser testing is incredibly powerful and useful for this project.
+- Browser tests should live in `tests/Browser/`.
+- Use the `search-docs` tool for detailed guidance on utilizing these features.
+
+### Browser Testing
+- You can use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories within Pest v4 browser tests, as well as `RefreshDatabase` (when needed) to ensure a clean state for each test.
+- Interact with the page (click, type, scroll, select, submit, drag-and-drop, touch gestures, etc.) when appropriate to complete the test.
+- If requested, test on multiple browsers (Chrome, Firefox, Safari).
+- If requested, test on different devices and viewports (like iPhone 14 Pro, tablets, or custom breakpoints).
+- Switch color schemes (light/dark mode) when appropriate.
+- Take screenshots or pause tests for debugging when appropriate.
+
+### Example Tests
+
+<code-snippet name="Pest Browser Test Example" lang="php">
+it('may reset the password', function () {
+    Notification::fake();
+
+    $this->actingAs(User::factory()->create());
+
+    $page = visit('/sign-in'); // Visit on a real browser...
+
+    $page->assertSee('Sign In')
+        ->assertNoJavascriptErrors() // or ->assertNoConsoleLogs()
+        ->click('Forgot Password?')
+        ->fill('email', 'nuno@laravel.com')
+        ->click('Send Reset Link')
+        ->assertSee('We have emailed your password reset link!')
+
+    Notification::assertSent(ResetPassword::class);
+});
+</code-snippet>
+
+<code-snippet name="Pest Smoke Testing Example" lang="php">
+$pages = visit(['/', '/about', '/contact']);
+
+$pages->assertNoJavascriptErrors()->assertNoConsoleLogs();
+</code-snippet>
+
+
+=== tailwindcss/core rules ===
+
+## Tailwind Core
+
+- Use Tailwind CSS classes to style HTML, check and use existing tailwind conventions within the project before writing your own.
+- Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc..)
+- Think through class placement, order, priority, and defaults - remove redundant classes, add classes to parent or child carefully to limit repetition, group elements logically
+- You can use the `search-docs` tool to get exact examples from the official documentation when needed.
+
+### Spacing
+- When listing items, use gap utilities for spacing, don't use margins.
+
+    <code-snippet name="Valid Flex Gap Spacing Example" lang="html">
+        <div class="flex gap-8">
+            <div>Superior</div>
+            <div>Michigan</div>
+            <div>Erie</div>
+        </div>
+    </code-snippet>
+
+
+### Dark Mode
+- If existing pages and components support dark mode, new pages and components must support dark mode in a similar way, typically using `dark:`.
+
+
+=== tailwindcss/v4 rules ===
+
+## Tailwind 4
+
+- Always use Tailwind CSS v4 - do not use the deprecated utilities.
+- `corePlugins` is not supported in Tailwind v4.
+- In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed.
+<code-snippet name="Extending Theme in CSS" lang="css">
+@theme {
+  --color-brand: oklch(0.72 0.11 178);
+}
+</code-snippet>
+
+- In Tailwind v4, you import Tailwind using a regular CSS `@import` statement, not using the `@tailwind` directives used in v3:
+
+<code-snippet name="Tailwind v4 Import Tailwind Diff" lang="diff">
+   - @tailwind base;
+   - @tailwind components;
+   - @tailwind utilities;
+   + @import "tailwindcss";
+</code-snippet>
+
+
+### Replaced Utilities
+- Tailwind v4 removed deprecated utilities. Do not use the deprecated option - use the replacement.
+- Opacity values are still numeric.
+
+| Deprecated |	Replacement |
+|------------+--------------|
+| bg-opacity-* | bg-black/* |
+| text-opacity-* | text-black/* |
+| border-opacity-* | border-black/* |
+| divide-opacity-* | divide-black/* |
+| ring-opacity-* | ring-black/* |
+| placeholder-opacity-* | placeholder-black/* |
+| flex-shrink-* | shrink-* |
+| flex-grow-* | grow-* |
+| overflow-ellipsis | text-ellipsis |
+| decoration-slice | box-decoration-slice |
+| decoration-clone | box-decoration-clone |
+</laravel-boost-guidelines>

README.md

@@ -27,6 +27,26 @@ ## TenantPilot setup
   - Ensure queue workers are running for jobs (e.g., policy sync) after deploy.
   - Keep secrets/env in Dokploy, never in code.
 
+## Intune RBAC Onboarding Wizard
+
+- Entry point: Tenant detail in Filament (`Setup Intune RBAC` in the ⋯ ActionGroup). Visible only for active tenants with `app_client_id`.
+- Flow (synchronous, delegated):
+  1) Configure Role (default Policy/Profile Manager), Scope (global or scope group), Group mode (create default `TenantPilot-Intune-RBAC` or pick existing security-enabled group). Review planned changes.
+  2) Delegated admin login (short-lived token, **not** stored in DB/cache).
+  3) Execute: resolve service principal, ensure/validate security group, ensure membership, ensure/create/patch Intune role assignment; persists IDs on tenant for idempotency; no queue.
+  4) Post-verify: forces fresh token, runs canary reads (deviceConfigurations/deviceCompliancePolicies; CA canary only if feature enabled), updates health and warnings (scope-limited, CA disabled, manual assignment required).
+- Safety/notes: least-privilege default, idempotent reruns, “already exists” treated as success. If service principal missing, run Admin consent first. Scope-limited setups may yield partial inventory/restore; warnings are surfaced in UI and health panel.
+
+## Graph Contract Registry & Drift Guard
+
+- Registry: `config/graph_contracts.php` defines per-type contracts (resource paths, allowed `$select`/`$expand`, @odata.type family, create/update methods, id field, hydration).
+- Client behavior:
+  - Sanitizes `$select`/`$expand` to allowed fields; logs warnings on trim.
+  - Derived @odata.type values within the family are accepted for preview/restore routing.
+  - Capability fallback: on 400s related to select/expand, retries without those clauses and surfaces warnings.
+- Drift check: `php artisan graph:contract:check [--tenant=]` runs lightweight probes against contract endpoints to detect capability/shape issues; useful in staging/CI (prod optional).
+- If Graph returns capability errors, TenantPilot downgrades safely, records warnings/audit entries, and avoids breaking preview/restore flows.
+
 ## Policy Settings Display
 
 - Policy detail pages render normalized settings instead of raw JSON:
@@ -36,6 +56,20 @@ ## Policy Settings Display
 - Version detail pages show both pretty-printed JSON and normalized settings.
 - Warnings surface malformed snapshots or @odata.type mismatches before restore.
 
+## Policy JSON Viewer (Feature 002)
+
+- **Location**: Policy View pages (`/admin/policies/{record}`)
+- **Capability**: Pretty-printed JSON snapshot viewer with copy-to-clipboard
+- **Settings Catalog Enhancement**: Dual-view tabs (Settings table + JSON viewer) for Settings Catalog policies
+- **Features**:
+  - Copy JSON to clipboard with success message
+  - Large payload detection (>500 KB) with warning badge and auto-collapse
+  - Dark mode support integrated with Filament design system
+  - Browser native search (Cmd+F / Ctrl+F) for finding specific keys or values
+  - Scrollable container with max height to prevent page overflow
+- **Usage**: See `specs/002-filament-json/quickstart.md` for detailed examples and configuration
+- **Performance**: Optimized for payloads up to 1 MB; auto-collapse improves initial render for large snapshots
+
 ## About Laravel
 
 Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

app/Console/Commands/GraphContractCheck.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Graph\GraphClientInterface;
+use Illuminate\Console\Command;
+
+class GraphContractCheck extends Command
+{
+    protected $signature = 'graph:contract:check {--tenant=}';
+
+    protected $description = 'Validate Graph contract registry against live endpoints (lightweight probes)';
+
+    public function handle(GraphClientInterface $graph): int
+    {
+        $contracts = config('graph_contracts.types', []);
+
+        if (empty($contracts)) {
+            $this->warn('No graph contracts configured.');
+
+            return self::SUCCESS;
+        }
+
+        $tenant = $this->option('tenant');
+        $failures = 0;
+
+        foreach ($contracts as $type => $contract) {
+            $resource = $contract['resource'] ?? null;
+            $select = $contract['allowed_select'] ?? [];
+            $expand = $contract['allowed_expand'] ?? [];
+
+            if (! $resource) {
+                $this->error("[$type] missing resource path");
+                $failures++;
+
+                continue;
+            }
+
+            $query = array_filter([
+                '$top' => 1,
+                '$select' => $select,
+                '$expand' => $expand,
+            ]);
+
+            $response = $graph->request('GET', $resource, [
+                'query' => $query,
+                'tenant' => $tenant,
+            ]);
+
+            if ($response->failed()) {
+                $code = $response->meta['error_code'] ?? $response->status;
+                $message = $response->meta['error_message'] ?? ($response->errors[0]['message'] ?? $response->errors[0] ?? 'unknown');
+                $this->error("[$type] drift or capability issue ({$code}): {$message}");
+                $failures++;
+
+                continue;
+            }
+
+            if (! empty($response->warnings)) {
+                $this->warn("[$type] completed with warnings: ".implode('; ', $response->warnings));
+            } else {
+                $this->info("[$type] OK");
+            }
+        }
+
+        return $failures > 0 ? self::FAILURE : self::SUCCESS;
+    }
+}

app/Console/Commands/TestSettingsCatalogCache.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\Policy;
+use App\Models\SettingsCatalogDefinition;
+use App\Services\Intune\PolicySnapshotService;
+use Illuminate\Console\Command;
+
+class TestSettingsCatalogCache extends Command
+{
+    protected $signature = 'test:settings-catalog-cache';
+
+    protected $description = 'Test Settings Catalog definition caching';
+
+    public function handle(PolicySnapshotService $snapshotService): int
+    {
+        $this->info('Finding Settings Catalog policy...');
+
+        $policy = Policy::where('policy_type', 'settingsCatalogPolicy')
+            ->whereHas('versions', function ($q) {
+                $q->whereRaw("jsonb_array_length(snapshot->'settings') > 0");
+            })
+            ->first();
+
+        if (! $policy) {
+            $this->error('No Settings Catalog policy with settings found');
+
+            return 1;
+        }
+
+        $this->info("Testing with policy: {$policy->name} (ID: {$policy->id})");
+        $this->info('Creating new snapshot...');
+
+        $tenant = $policy->tenant;
+        if (! $tenant) {
+            $this->error('Policy has no tenant');
+
+            return 1;
+        }
+
+        $result = $snapshotService->fetch($tenant, $policy, 'test@example.com');
+
+        if (isset($result['failure'])) {
+            $this->error('Snapshot failed: '.($result['failure']['reason'] ?? 'Unknown'));
+
+            return 1;
+        }
+
+        // Extract snapshot data from result
+        $snapshotData = [
+            'payload' => $result['payload'] ?? [],
+            'metadata' => $result['metadata'] ?? [],
+        ];
+
+        // Create PolicyVersion to save the snapshot
+        $policy->versions()->create([
+            'tenant_id' => $policy->tenant_id,
+            'version_number' => $policy->versions()->max('version_number') + 1,
+            'policy_type' => $policy->policy_type,
+            'platform' => $policy->platform,
+            'created_by' => 'test@example.com',
+            'captured_at' => now(),
+            'snapshot' => $snapshotData,
+        ]);
+
+        $this->info('✓ Snapshot created and saved successfully!');
+        $this->newLine();
+
+        $latestSnapshot = $policy->versions()->orderByDesc('captured_at')->first();
+        $metadata = $latestSnapshot->snapshot['metadata'] ?? [];
+
+        $this->table(
+            ['Key', 'Value'],
+            [
+                ['definitions_cached', $metadata['definitions_cached'] ?? 'NOT SET'],
+                ['definition_count', $metadata['definition_count'] ?? 'NOT SET'],
+                ['settings_hydration', $metadata['settings_hydration'] ?? 'NOT SET'],
+                ['Cached definitions in DB', SettingsCatalogDefinition::count()],
+            ]
+        );
+
+        if (isset($metadata['definitions_cached']) && $metadata['definitions_cached']) {
+            $this->info('✓ Definitions successfully cached!');
+
+            return 0;
+        } else {
+            $this->warn('⚠ Definitions not cached - check logs for errors');
+
+            return 1;
+        }
+    }
+}

app/Filament/Resources/PolicyResource.php

@@ -9,8 +9,12 @@
 use App\Services\Intune\PolicyNormalizer;
 use BackedEnum;
 use Filament\Actions;
-use Filament\Infolists;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Infolists\Components\ViewEntry;
 use Filament\Resources\Resource;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Components\Tabs;
+use Filament\Schemas\Components\Tabs\Tab;
 use Filament\Schemas\Schema;
 use Filament\Tables;
 use Filament\Tables\Table;
@@ -34,25 +38,151 @@ public static function infolist(Schema $schema): Schema
     {
         return $schema
             ->schema([
-                Infolists\Components\TextEntry::make('display_name')->label('Policy'),
+                Section::make('Policy Details')
-                Infolists\Components\TextEntry::make('policy_type')->label('Type'),
+                    ->schema([
-                Infolists\Components\TextEntry::make('platform'),
+                        TextEntry::make('display_name')->label('Policy'),
-                Infolists\Components\TextEntry::make('external_id')->label('External ID'),
+                        TextEntry::make('policy_type')->label('Type'),
-                Infolists\Components\TextEntry::make('last_synced_at')->dateTime()->label('Last synced'),
+                        TextEntry::make('platform'),
-                Infolists\Components\TextEntry::make('created_at')->since(),
+                        TextEntry::make('external_id')->label('External ID'),
-                Infolists\Components\ViewEntry::make('settings')
+                        TextEntry::make('last_synced_at')->dateTime()->label('Last synced'),
-                    ->label('Settings')
+                        TextEntry::make('created_at')->since(),
-                    ->view('filament.infolists.entries.normalized-settings')
+                    ])
-                    ->state(function (Policy $record) {
+                    ->columns(2),
-                        $snapshot = $record->versions()
-                            ->orderByDesc('captured_at')
-                            ->value('snapshot');
 
-                        return app(PolicyNormalizer::class)->normalize(
+                // For Settings Catalog policies: Tabs with Settings table + JSON viewer
-                            is_array($snapshot) ? $snapshot : [],
+                Tabs::make('policy_content')
-                            $record->policy_type ?? '',
+                    ->tabs([
-                            $record->platform
+                        Tab::make('Settings')
-                        );
+                            ->schema([
+                                ViewEntry::make('settings_grouped')
+                                    ->label('')
+                                    ->view('filament.infolists.entries.settings-catalog-grouped')
+                                    ->state(function (Policy $record) {
+                                        $snapshot = static::latestSnapshot($record);
+
+                                        $settings = $snapshot['payload']['settings'] ?? $snapshot['settings'] ?? [];
+                                        if (empty($settings)) {
+                                            return ['groups' => []];
+                                        }
+
+                                        return app(PolicyNormalizer::class)->normalizeSettingsCatalogGrouped($settings);
+                                    })
+                                    ->visible(fn (Policy $record) => $record->policy_type === 'settingsCatalogPolicy' &&
+                                        $record->versions()->exists()
+                                    ),
+
+                                ViewEntry::make('settings_standard')
+                                    ->label('')
+                                    ->view('filament.infolists.entries.policy-settings-standard')
+                                    ->state(function (Policy $record) {
+                                        $snapshot = static::latestSnapshot($record);
+
+                                        $normalizer = app(PolicyNormalizer::class);
+
+                                        return $normalizer->normalize(
+                                            $snapshot,
+                                            $record->policy_type,
+                                            $record->platform
+                                        );
+                                    })
+                                    ->visible(fn (Policy $record) => $record->policy_type !== 'settingsCatalogPolicy' &&
+                                        $record->versions()->exists()
+                                    ),
+
+                                TextEntry::make('no_settings_available')
+                                    ->label('Settings')
+                                    ->state('No policy snapshot available yet.')
+                                    ->helperText('This policy has been inventoried but no configuration snapshot has been captured yet.')
+                                    ->visible(fn (Policy $record) => ! $record->versions()->exists()),
+                            ]),
+                        Tab::make('JSON')
+                            ->schema([
+                                ViewEntry::make('snapshot_json')
+                                    ->view('filament.infolists.entries.snapshot-json')
+                                    ->state(fn (Policy $record) => static::latestSnapshot($record))
+                                    ->columnSpanFull(),
+                                TextEntry::make('snapshot_size')
+                                    ->label('Payload Size')
+                                    ->state(fn (Policy $record) => strlen(json_encode(static::latestSnapshot($record) ?: [])))
+                                    ->formatStateUsing(function ($state) {
+                                        if ($state > 512000) {
+                                            return '<span class="inline-flex items-center gap-1 text-warning-600 dark:text-warning-400 font-semibold">
+                                                <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
+                                                    <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd"/>
+                                                </svg>
+                                                Large payload ('.number_format($state / 1024, 0).' KB) - May impact performance
+                                            </span>';
+                                        }
+
+                                        return number_format($state / 1024, 1).' KB';
+                                    })
+                                    ->html()
+                                    ->visible(fn (Policy $record) => strlen(json_encode(static::latestSnapshot($record) ?: [])) > 512000),
+                            ])
+                            ->visible(fn (Policy $record) => $record->versions()->exists()),
+                    ])
+                    ->visible(function (Policy $record) {
+                        return str_contains(strtolower($record->policy_type ?? ''), 'settings') ||
+                               str_contains(strtolower($record->policy_type ?? ''), 'catalog');
+                    }),
+
+                // For non-Settings Catalog policies: Simple sections without tabs
+                Section::make('Settings')
+                    ->schema([
+                        ViewEntry::make('settings')
+                            ->label('')
+                            ->view('filament.infolists.entries.normalized-settings')
+                            ->state(function (Policy $record) {
+                                $normalized = app(PolicyNormalizer::class)->normalize(
+                                    static::latestSnapshot($record),
+                                    $record->policy_type ?? '',
+                                    $record->platform
+                                );
+
+                                $normalized['context'] = 'policy';
+                                $normalized['record_id'] = (string) $record->getKey();
+
+                                return $normalized;
+                            }),
+                    ])
+                    ->visible(function (Policy $record) {
+                        // Show simple settings section for non-Settings Catalog policies
+                        return ! str_contains(strtolower($record->policy_type ?? ''), 'settings') &&
+                               ! str_contains(strtolower($record->policy_type ?? ''), 'catalog');
+                    }),
+
+                Section::make('Policy Snapshot (JSON)')
+                    ->schema([
+                        ViewEntry::make('snapshot_json')
+                            ->view('filament.infolists.entries.snapshot-json')
+                            ->state(fn (Policy $record) => static::latestSnapshot($record))
+                            ->columnSpanFull(),
+
+                        TextEntry::make('snapshot_size')
+                            ->label('Payload Size')
+                            ->state(fn (Policy $record) => strlen(json_encode(static::latestSnapshot($record) ?: [])))
+                            ->formatStateUsing(function ($state) {
+                                if ($state > 512000) {
+                                    return '<span class="inline-flex items-center gap-1 text-warning-600 dark:text-warning-400 font-semibold">
+                                        <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
+                                            <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd"/>
+                                        </svg>
+                                        Large payload ('.number_format($state / 1024, 0).' KB) - May impact performance
+                                    </span>';
+                                }
+
+                                return number_format($state / 1024, 1).' KB';
+                            })
+                            ->html()
+                            ->visible(fn (Policy $record) => strlen(json_encode(static::latestSnapshot($record) ?: [])) > 512000),
+                    ])
+                    ->collapsible()
+                    ->collapsed(fn (Policy $record) => strlen(json_encode(static::latestSnapshot($record) ?: [])) > 512000)
+                    ->description('Raw JSON configuration from Microsoft Graph API')
+                    ->visible(function (Policy $record) {
+                        // Show standalone JSON section only for non-Settings Catalog policies
+                        return ! str_contains(strtolower($record->policy_type ?? ''), 'settings') &&
+                               ! str_contains(strtolower($record->policy_type ?? ''), 'catalog');
                     }),
             ]);
     }
@@ -79,11 +209,23 @@ public static function table(Table $table): Table
                 Tables\Columns\TextColumn::make('platform')
                     ->badge()
                     ->sortable(),
-                Tables\Columns\TextColumn::make('versions_count')
+                Tables\Columns\TextColumn::make('settings_status')
                     ->label('Settings')
                     ->badge()
-                    ->state(fn (Policy $record) => $record->versions_count > 0 ? 'Available' : 'Missing')
+                    ->state(function (Policy $record) {
-                    ->color(fn (Policy $record) => $record->versions_count > 0 ? 'success' : 'gray'),
+                        $latest = $record->versions->first();
+                        $snapshot = $latest?->snapshot ?? [];
+                        $hasSettings = is_array($snapshot) && ! empty($snapshot['settings']);
+
+                        return $hasSettings ? 'Available' : 'Missing';
+                    })
+                    ->color(function (Policy $record) {
+                        $latest = $record->versions->first();
+                        $snapshot = $latest?->snapshot ?? [];
+                        $hasSettings = is_array($snapshot) && ! empty($snapshot['settings']);
+
+                        return $hasSettings ? 'success' : 'gray';
+                    }),
                 Tables\Columns\TextColumn::make('external_id')
                     ->label('External ID')
                     ->copyable()
@@ -99,7 +241,12 @@ public static function table(Table $table): Table
             ])
             ->filters([
                 Tables\Filters\SelectFilter::make('policy_type')
-                    ->options(fn () => Policy::query()->distinct()->pluck('policy_type', 'policy_type')->all()),
+                    ->options(function () {
+                        return collect(config('tenantpilot.supported_policy_types', []))
+                            ->pluck('label', 'type')
+                            ->map(fn ($label, $type) => $label ?? $type)
+                            ->all();
+                    }),
                 Tables\Filters\SelectFilter::make('category')
                     ->options(function () {
                         return collect(config('tenantpilot.supported_policy_types', []))
@@ -137,7 +284,10 @@ public static function getEloquentQuery(): Builder
 
         return parent::getEloquentQuery()
             ->when($tenantId, fn (Builder $query) => $query->where('tenant_id', $tenantId))
-            ->withCount('versions');
+            ->withCount('versions')
+            ->with([
+                'versions' => fn ($query) => $query->orderByDesc('captured_at')->limit(1),
+            ]);
     }
 
     public static function getRelations(): array
@@ -155,6 +305,24 @@ public static function getPages(): array
         ];
     }
 
+    private static function latestSnapshot(Policy $record): array
+    {
+        $snapshot = $record->relationLoaded('versions')
+            ? $record->versions->first()?->snapshot
+            : $record->versions()->orderByDesc('captured_at')->value('snapshot');
+
+        if (is_string($snapshot)) {
+            $decoded = json_decode($snapshot, true);
+            $snapshot = $decoded ?? [];
+        }
+
+        if (is_array($snapshot)) {
+            return $snapshot;
+        }
+
+        return [];
+    }
+
     /**
      * @return array{label:?string,category:?string,restore:?string,risk:?string}|array<string,string>|array<string,mixed>
      */

app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php

@@ -3,9 +3,54 @@
 namespace App\Filament\Resources\PolicyResource\Pages;
 
 use App\Filament\Resources\PolicyResource;
+use App\Services\Intune\VersionService;
+use Filament\Actions\Action;
+use Filament\Notifications\Notification;
 use Filament\Resources\Pages\ViewRecord;
 
 class ViewPolicy extends ViewRecord
 {
     protected static string $resource = PolicyResource::class;
+
+    protected function getActions(): array
+    {
+        return [
+            Action::make('capture_snapshot')
+                ->label('Capture snapshot')
+                ->requiresConfirmation()
+                ->modalHeading('Capture snapshot now')
+                ->modalSubheading('This will fetch the latest configuration from Microsoft Graph and store a new policy version.')
+                ->action(function () {
+                    $policy = $this->record;
+
+                    try {
+                        $tenant = $policy->tenant;
+
+                        if (! $tenant) {
+                            Notification::make()
+                                ->title('Policy has no tenant associated.')
+                                ->danger()
+                                ->send();
+
+                            return;
+                        }
+
+                        app(VersionService::class)->captureFromGraph($tenant, $policy, auth()->user()?->email ?? null);
+
+                        Notification::make()
+                            ->title('Snapshot captured successfully.')
+                            ->success()
+                            ->send();
+
+                        $this->redirect($this->getResource()::getUrl('view', ['record' => $policy->getKey()]));
+                    } catch (\Throwable $e) {
+                        Notification::make()
+                            ->title('Failed to capture snapshot: '.$e->getMessage())
+                            ->danger()
+                            ->send();
+                    }
+                })
+                ->color('primary'),
+        ];
+    }
 }

app/Filament/Resources/PolicyVersionResource.php

@@ -12,6 +12,8 @@
 use Filament\Infolists;
 use Filament\Notifications\Notification;
 use Filament\Resources\Resource;
+use Filament\Schemas\Components\Tabs;
+use Filament\Schemas\Components\Tabs\Tab;
 use Filament\Schemas\Schema;
 use Filament\Tables;
 use Filament\Tables\Table;
@@ -35,49 +37,65 @@ public static function infolist(Schema $schema): Schema
                 Infolists\Components\TextEntry::make('platform'),
                 Infolists\Components\TextEntry::make('created_by')->label('Actor'),
                 Infolists\Components\TextEntry::make('captured_at')->dateTime(),
-                Infolists\Components\ViewEntry::make('snapshot_pretty')
+                Tabs::make()
-                    ->label('Raw JSON')
+                    ->activeTab(1)
-                    ->view('filament.infolists.entries.snapshot-json')
+                    ->persistTabInQueryString('tab')
-                    ->state(fn (PolicyVersion $record) => $record->snapshot ?? []),
+                    ->tabs([
-                Infolists\Components\ViewEntry::make('normalized_settings')
+                        Tab::make('Normalized settings')
-                    ->label('Normalized settings')
+                            ->schema([
-                    ->view('filament.infolists.entries.normalized-settings')
+                                Infolists\Components\ViewEntry::make('normalized_settings')
-                    ->state(function (PolicyVersion $record) {
+                                    ->view('filament.infolists.entries.normalized-settings')
-                        return app(PolicyNormalizer::class)->normalize(
+                                    ->state(function (PolicyVersion $record) {
-                            is_array($record->snapshot) ? $record->snapshot : [],
+                                        $normalized = app(PolicyNormalizer::class)->normalize(
-                            $record->policy_type ?? '',
+                                            is_array($record->snapshot) ? $record->snapshot : [],
-                            $record->platform
+                                            $record->policy_type ?? '',
-                        );
+                                            $record->platform
-                    }),
+                                        );
-                Infolists\Components\TextEntry::make('diff')
-                    ->label('Diff vs previous')
-                    ->state(function (PolicyVersion $record) {
-                        $previous = $record->previous();
 
-                        if (! $previous) {
+                                        $normalized['context'] = 'version';
-                            return ['summary' => 'No previous version'];
+                                        $normalized['record_id'] = (string) $record->getKey();
-                        }
 
-                        return app(VersionDiff::class)
+                                        return $normalized;
-                            ->compare($previous->snapshot ?? [], $record->snapshot ?? []);
+                                    }),
-                    })
+                            ]),
-                    ->formatStateUsing(fn ($state) => json_encode($state ?? [], JSON_PRETTY_PRINT))
+                        Tab::make('Raw JSON')
-                    ->copyable(),
+                            ->schema([
-                Infolists\Components\ViewEntry::make('normalized_diff')
+                                Infolists\Components\ViewEntry::make('snapshot_pretty')
-                    ->label('Normalized diff')
+                                    ->view('filament.infolists.entries.snapshot-json')
-                    ->view('filament.infolists.entries.normalized-diff')
+                                    ->state(fn (PolicyVersion $record) => $record->snapshot ?? []),
-                    ->state(function (PolicyVersion $record) {
+                            ]),
-                        $normalizer = app(PolicyNormalizer::class);
+                        Tab::make('Diff')
-                        $diff = app(VersionDiff::class);
+                            ->schema([
+                                Infolists\Components\ViewEntry::make('normalized_diff')
+                                    ->view('filament.infolists.entries.normalized-diff')
+                                    ->state(function (PolicyVersion $record) {
+                                        $normalizer = app(PolicyNormalizer::class);
+                                        $diff = app(VersionDiff::class);
 
-                        $previous = $record->previous();
+                                        $previous = $record->previous();
-                        $from = $previous
+                                        $from = $previous
-                            ? $normalizer->flattenForDiff($previous->snapshot ?? [], $previous->policy_type ?? '', $previous->platform)
+                                            ? $normalizer->flattenForDiff($previous->snapshot ?? [], $previous->policy_type ?? '', $previous->platform)
-                            : [];
+                                            : [];
-                        $to = $normalizer->flattenForDiff($record->snapshot ?? [], $record->policy_type ?? '', $record->platform);
+                                        $to = $normalizer->flattenForDiff($record->snapshot ?? [], $record->policy_type ?? '', $record->platform);
 
-                        return $diff->compare($from, $to);
+                                        return $diff->compare($from, $to);
-                    }),
+                                    }),
+                                Infolists\Components\TextEntry::make('diff')
+                                    ->label('Diff JSON vs previous')
+                                    ->state(function (PolicyVersion $record) {
+                                        $previous = $record->previous();
+
+                                        if (! $previous) {
+                                            return ['summary' => 'No previous version'];
+                                        }
+
+                                        return app(VersionDiff::class)
+                                            ->compare($previous->snapshot ?? [], $record->snapshot ?? []);
+                                    })
+                                    ->formatStateUsing(fn ($state) => json_encode($state ?? [], JSON_PRETTY_PRINT))
+                                    ->copyable(),
+                            ]),
+                    ]),
             ]);
     }
 

app/Filament/Resources/RestoreRunResource.php

@@ -182,10 +182,10 @@ public static function infolist(Schema $schema): Schema
                     ->label('Preview')
                     ->view('filament.infolists.entries.restore-preview')
                     ->state(fn ($record) => $record->preview ?? []),
-                Infolists\Components\TextEntry::make('results')
+                Infolists\Components\ViewEntry::make('results')
                     ->label('Results')
-                    ->formatStateUsing(fn ($state) => json_encode($state ?? [], JSON_PRETTY_PRINT))
+                    ->view('filament.infolists.entries.restore-results')
-                    ->copyable(),
+                    ->state(fn ($record) => $record->results ?? []),
             ]);
     }
 

app/Livewire/SettingsCatalogSettingsTable.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace App\Livewire;
+
+use Filament\Actions\Action;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Table;
+use Filament\Tables\TableComponent;
+use Illuminate\Contracts\View\View;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Str;
+
+class SettingsCatalogSettingsTable extends TableComponent
+{
+    /**
+     * @var array<int, array<string, mixed>>
+     */
+    public array $settingsRows = [];
+
+    public string $context = 'policy';
+
+    /**
+     * @param  array<int, array<string, mixed>>  $settingsRows
+     */
+    public function mount(array $settingsRows = [], string $context = 'policy'): void
+    {
+        $this->settingsRows = $settingsRows;
+        $this->context = $context;
+    }
+
+    public function table(Table $table): Table
+    {
+        return $table
+            ->queryStringIdentifier('settingsCatalog'.Str::studly($this->context))
+            ->records(function (?string $search, int|string $page, int|string $recordsPerPage, ?string $sortColumn, ?string $sortDirection): LengthAwarePaginator {
+                $records = collect($this->settingsRows);
+
+                if (filled($search)) {
+                    $needle = Str::lower($search);
+
+                    $records = $records->filter(function (array $row) use ($needle): bool {
+                        $haystack = implode(' ', [
+                            (string) ($row['definition'] ?? ''),
+                            (string) ($row['type'] ?? ''),
+                            (string) ($row['value'] ?? ''),
+                            (string) ($row['path'] ?? ''),
+                        ]);
+
+                        return Str::contains(Str::lower($haystack), $needle);
+                    });
+                }
+
+                if (filled($sortColumn)) {
+                    $direction = Str::lower((string) ($sortDirection ?? 'asc')) === 'desc' ? 'desc' : 'asc';
+
+                    $records = $records->sortBy(
+                        fn (array $row) => (string) ($row[$sortColumn] ?? ''),
+                        SORT_NATURAL | SORT_FLAG_CASE,
+                        $direction === 'desc'
+                    );
+                }
+
+                $perPage = is_numeric($recordsPerPage) ? max(1, (int) $recordsPerPage) : 25;
+                $currentPage = is_numeric($page) ? max(1, (int) $page) : 1;
+
+                $total = $records->count();
+                $items = $records->forPage($currentPage, $perPage)->values();
+
+                return new LengthAwarePaginator(
+                    $items,
+                    $total,
+                    $perPage,
+                    $currentPage
+                );
+            })
+            ->paginated([25, 50, 100])
+            ->defaultPaginationPageOption(25)
+            ->searchable()
+            ->searchPlaceholder('Search definition/value…')
+            ->striped()
+            ->deferLoading(! app()->runningUnitTests())
+            ->columns([
+                TextColumn::make('definition')
+                    ->label('Definition')
+                    ->limit(60)
+                    ->tooltip(fn (?string $state): ?string => filled($state) ? $state : null)
+                    ->searchable()
+                    ->extraAttributes(['class' => 'font-mono text-xs']),
+                TextColumn::make('type')
+                    ->label('Type')
+                    ->limit(50)
+                    ->tooltip(fn (?string $state): ?string => filled($state) ? $state : null)
+                    ->toggleable()
+                    ->extraAttributes(['class' => 'font-mono text-xs']),
+                TextColumn::make('value')
+                    ->label('Value')
+                    ->badge(fn (?string $state): bool => $state === '(group)')
+                    ->color(fn (?string $state): string => $state === '(group)' ? 'gray' : 'primary')
+                    ->limit(60)
+                    ->tooltip(fn (?string $state): ?string => filled($state) ? $state : null)
+                    ->searchable(),
+                TextColumn::make('path')
+                    ->label('Path')
+                    ->limit(80)
+                    ->tooltip(fn (?string $state): ?string => filled($state) ? $state : null)
+                    ->toggleable(isToggledHiddenByDefault: true)
+                    ->extraAttributes(['class' => 'font-mono text-xs']),
+            ])
+            ->actions([
+                Action::make('details')
+                    ->label('Details')
+                    ->icon('heroicon-m-eye')
+                    ->slideOver()
+                    ->modalSubmitAction(false)
+                    ->modalCancelActionLabel('Close')
+                    ->modalHeading(fn (array $record): string => (string) ($record['definition'] ?? 'Setting details'))
+                    ->modalContent(fn (array $record): View => view('filament.modals.settings-catalog-setting-details', ['record' => $record])),
+            ]);
+    }
+
+    public function render(): View
+    {
+        return view('livewire.settings-catalog-settings-table');
+    }
+}

app/Models/SettingsCatalogDefinition.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class SettingsCatalogDefinition extends Model
+{
+    protected $fillable = [
+        'definition_id',
+        'display_name',
+        'description',
+        'help_text',
+        'category_id',
+        'ux_behavior',
+        'raw',
+    ];
+
+    protected $casts = [
+        'raw' => 'array',
+    ];
+
+    /**
+     * Find a definition by its definition_id.
+     */
+    public static function findByDefinitionId(string $definitionId): ?self
+    {
+        return static::where('definition_id', $definitionId)->first();
+    }
+
+    /**
+     * Find multiple definitions by their definition_ids.
+     */
+    public static function findByDefinitionIds(array $definitionIds): \Illuminate\Support\Collection
+    {
+        return static::whereIn('definition_id', $definitionIds)->get()->keyBy('definition_id');
+    }
+}

app/Services/Graph/GraphContractRegistry.php

@@ -0,0 +1,381 @@
+<?php
+
+namespace App\Services\Graph;
+
+use Illuminate\Support\Arr;
+
+class GraphContractRegistry
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function get(string $policyType): array
+    {
+        return config("graph_contracts.types.$policyType", []);
+    }
+
+    /**
+     * @param  array<string, mixed>  $query
+     * @return array{query: array<string, mixed>, warnings: array<int, string>}
+     */
+    public function sanitizeQuery(string $policyType, array $query): array
+    {
+        $contract = $this->get($policyType);
+        $allowedSelect = $contract['allowed_select'] ?? [];
+        $allowedExpand = $contract['allowed_expand'] ?? [];
+        $warnings = [];
+
+        if (! empty($query['$select']) && is_array($query['$select'])) {
+            $original = $query['$select'];
+            $query['$select'] = array_values(array_intersect($original, $allowedSelect));
+
+            if (count($query['$select']) !== count($original)) {
+                $warnings[] = 'Trimmed unsupported $select fields for capability safety.';
+            }
+        }
+
+        if (! empty($query['$expand']) && is_array($query['$expand'])) {
+            $original = $query['$expand'];
+            $query['$expand'] = array_values(array_intersect($original, $allowedExpand));
+
+            if (count($query['$expand']) !== count($original)) {
+                $warnings[] = 'Trimmed unsupported $expand fields for capability safety.';
+            }
+        }
+
+        return [
+            'query' => $query,
+            'warnings' => $warnings,
+        ];
+    }
+
+    public function matchesTypeFamily(string $policyType, ?string $odataType): bool
+    {
+        if ($odataType === null) {
+            return false;
+        }
+
+        $family = config("graph_contracts.types.$policyType.type_family", []);
+
+        return in_array(strtolower($odataType), array_map('strtolower', $family), true);
+    }
+
+    /**
+     * Sanitize update payloads based on contract metadata.
+     */
+    public function sanitizeUpdatePayload(string $policyType, array $snapshot): array
+    {
+        $contract = $this->get($policyType);
+        $whitelist = $contract['update_whitelist'] ?? null;
+        $stripKeys = array_merge($this->readOnlyKeys(), $contract['update_strip_keys'] ?? []);
+        $mapping = $contract['update_map'] ?? [];
+
+        $stripOdata = $whitelist !== null || ! empty($contract['update_strip_keys']);
+
+        $result = $this->sanitizeArray($snapshot, $whitelist, $stripKeys, $stripOdata, $mapping);
+
+        return $result;
+    }
+
+    public function subresourceSettingsPath(string $policyType, string $policyId): ?string
+    {
+        $subresources = config("graph_contracts.types.$policyType.subresources", []);
+        $settings = $subresources['settings'] ?? null;
+        $path = $settings['path'] ?? null;
+
+        if (! $path) {
+            return null;
+        }
+
+        return str_replace('{id}', urlencode($policyId), $path);
+    }
+
+    public function settingsWriteMethod(string $policyType): ?string
+    {
+        $contract = $this->get($policyType);
+        $write = $contract['settings_write'] ?? null;
+        $method = is_array($write) ? ($write['method'] ?? null) : null;
+
+        if (! is_string($method) || $method === '') {
+            return null;
+        }
+
+        return strtoupper($method);
+    }
+
+    public function settingsWritePath(string $policyType, string $policyId, string $settingId): ?string
+    {
+        $contract = $this->get($policyType);
+        $write = $contract['settings_write'] ?? null;
+        $template = is_array($write) ? ($write['path_template'] ?? null) : null;
+
+        if (! is_string($template) || $template === '') {
+            return null;
+        }
+
+        return str_replace(
+            ['{id}', '{settingId}'],
+            [urlencode($policyId), urlencode($settingId)],
+            $template
+        );
+    }
+
+    /**
+     * Sanitize a settings_apply payload for settingsCatalogPolicy.
+     * Preserves `@odata.type` inside `settingInstance` and nested children while
+     * stripping read-only/meta fields and ids that the server may reject.
+     *
+     * @param  array<int, mixed>|array<string,mixed>  $settings
+     * @return array<int, mixed>
+     */
+    public function sanitizeSettingsApplyPayload(string $policyType, array $settings): array
+    {
+        $clean = [];
+
+        foreach ($settings as $item) {
+            if (! is_array($item)) {
+                continue;
+            }
+
+            $clean[] = $this->sanitizeSettingsItem($item);
+        }
+
+        return $clean;
+    }
+
+    private function sanitizeSettingsItem(array $item): array
+    {
+        $result = [];
+        $hasSettingInstance = false;
+        $existingOdataType = null;
+
+        // First pass: collect information and process items
+        foreach ($item as $key => $value) {
+            if (strtolower($key) === 'id') {
+                continue;
+            }
+
+            if ($key === '@odata.type') {
+                $existingOdataType = $value;
+
+                continue;
+            }
+
+            if ($key === 'settingInstance' && is_array($value)) {
+                $hasSettingInstance = true;
+                $result[$key] = $this->preserveOdataTypesRecursively($value);
+
+                continue;
+            }
+
+            // For arrays, recurse into members but keep @odata.type where present
+            if (is_array($value)) {
+                $result[$key] = $this->sanitizeArray($value, null, $this->readOnlyKeys(), false, []);
+
+                continue;
+            }
+
+            $result[$key] = $value;
+        }
+
+        // Ensure top-level @odata.type is present and FIRST for Settings Catalog settings
+        // Microsoft Graph requires this to properly interpret the settingInstance type
+        $odataType = $existingOdataType ?? ($hasSettingInstance ? '#microsoft.graph.deviceManagementConfigurationSetting' : null);
+
+        if ($odataType) {
+            // Prepend @odata.type to ensure it appears first in JSON
+            $result = ['@odata.type' => $odataType] + $result;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Recursively preserve `@odata.type` keys inside settingInstance structures
+     * while stripping read-only keys and ids from nested objects/arrays.
+     *
+     * @param  array<string,mixed>  $node
+     * @return array<string,mixed>
+     */
+    private function preserveOdataTypesRecursively(array $node): array
+    {
+        $clean = [];
+
+        foreach ($node as $key => $value) {
+            $lower = strtolower((string) $key);
+
+            // strip id fields
+            if ($lower === 'id') {
+                continue;
+            }
+
+            if ($key === '@odata.type') {
+                $clean[$key] = $value;
+
+                continue;
+            }
+
+            if (is_array($value)) {
+                if (array_is_list($value)) {
+                    $clean[$key] = array_values(array_map(function ($child) {
+                        if (is_array($child)) {
+                            return $this->preserveOdataTypesRecursively($child);
+                        }
+
+                        return $child;
+                    }, $value));
+
+                    continue;
+                }
+
+                $clean[$key] = $this->preserveOdataTypesRecursively($value);
+
+                continue;
+            }
+
+            $clean[$key] = $value;
+        }
+
+        return $clean;
+    }
+
+    public function memberHydrationStrategy(string $policyType): ?string
+    {
+        return config("graph_contracts.types.$policyType.member_hydration_strategy");
+    }
+
+    /**
+     * Determine whether a failed response qualifies for capability downgrade retry.
+     */
+    public function shouldDowngradeOnCapabilityError(GraphResponse $response, array $query): bool
+    {
+        if (empty($query)) {
+            return false;
+        }
+
+        if ($response->status !== 400) {
+            return false;
+        }
+
+        $message = strtolower($response->meta['error_message'] ?? $this->firstErrorMessage($response->errors));
+
+        if ($message && (str_contains($message, '$select') || str_contains($message, '$expand') || str_contains($message, 'request is invalid'))) {
+            return true;
+        }
+
+        return ! empty($query['$select']) || ! empty($query['$expand']);
+    }
+
+    private function sanitizeArray(array $payload, ?array $whitelist, array $stripKeys, bool $stripOdata = false, array $mapping = []): array
+    {
+        $clean = [];
+        $normalizedWhitelist = $whitelist ? array_map('strtolower', $whitelist) : null;
+        $normalizedStrip = array_map('strtolower', $stripKeys);
+        $normalizedMapping = [];
+
+        foreach ($mapping as $source => $target) {
+            $normalizedMapping[strtolower($source)] = $target;
+        }
+
+        foreach ($payload as $key => $value) {
+            $normalizedKey = strtolower((string) $key);
+            $targetKey = $normalizedMapping[$normalizedKey] ?? $key;
+            $normalizedTargetKey = strtolower((string) $targetKey);
+
+            if ($normalizedWhitelist !== null) {
+                $targetKey = $normalizedTargetKey;
+            }
+
+            if ($this->shouldStripKey($normalizedKey, $normalizedStrip, $stripOdata)) {
+                continue;
+            }
+
+            if ($normalizedWhitelist !== null && ! in_array($normalizedTargetKey, $normalizedWhitelist, true)) {
+                continue;
+            }
+
+            if (is_array($value)) {
+                if (array_is_list($value)) {
+                    $clean[$targetKey] = array_values(array_filter(array_map(
+                        fn ($item) => is_array($item) ? $this->sanitizeArray($item, null, $stripKeys, $stripOdata, $mapping) : $item,
+                        $value
+                    ), fn ($item) => $item !== []));
+
+                    continue;
+                }
+
+                $clean[$targetKey] = $this->sanitizeArray($value, null, $stripKeys, $stripOdata, $mapping);
+
+                continue;
+            }
+
+            $clean[$targetKey] = $value;
+        }
+
+        return $clean;
+    }
+
+    private function shouldStripKey(string $normalizedKey, array $normalizedStrip, bool $stripOdata): bool
+    {
+        if (in_array($normalizedKey, $normalizedStrip, true)) {
+            return true;
+        }
+
+        if ($stripOdata && str_starts_with($normalizedKey, '@odata')) {
+            return true;
+        }
+
+        if ($stripOdata && str_contains($normalizedKey, '@odata.')) {
+            return true;
+        }
+
+        if ($stripOdata && str_contains($normalizedKey, '@odata')) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function readOnlyKeys(): array
+    {
+        return [
+            '@odata.context',
+            '@odata.etag',
+            '@odata.nextlink',
+            '@odata.deltalink',
+            'id',
+            'createddatetime',
+            'lastmodifieddatetime',
+            'version',
+            'supportsscopetags',
+            'createdby',
+            'lastmodifiedby',
+            'rolescopetagids@odata.bind',
+            'rolescopetagids@odata.navigationlink',
+            'rolescopetagids@odata.type',
+            'rolescopetagids',
+        ];
+    }
+
+    private function firstErrorMessage(array $errors): ?string
+    {
+        foreach ($errors as $error) {
+            if (is_array($error) && is_string(Arr::get($error, 'message'))) {
+                return Arr::get($error, 'message');
+            }
+
+            if (is_array($error) && is_string(Arr::get($error, 'error.message'))) {
+                return Arr::get($error, 'error.message');
+            }
+
+            if (is_string($error)) {
+                return $error;
+            }
+        }
+
+        return null;
+    }
+}

app/Services/Graph/MicrosoftGraphClient.php

@@ -32,8 +32,10 @@ class MicrosoftGraphClient implements GraphClientInterface
 
     private int $retrySleepMs;
 
-    public function __construct(private readonly GraphLogger $logger)
+    public function __construct(
-    {
+        private readonly GraphLogger $logger,
+        private readonly GraphContractRegistry $contracts,
+    ) {
         $this->baseUrl = rtrim(config('graph.base_url', 'https://graph.microsoft.com'), '/')
             .'/'.trim(config('graph.version', 'beta'), '/');
         $this->tokenUrlTemplate = config('graph.token_url', 'https://login.microsoftonline.com/%s/oauth2/v2.0/token');
@@ -69,7 +71,13 @@ public function listPolicies(string $policyType, array $options = []): GraphResp
             'client_request_id' => $clientRequestId,
         ]);
 
-        $response = $this->send('GET', $endpoint, ['query' => $query, 'client_request_id' => $clientRequestId], $context);
+        $sendOptions = ['query' => $query, 'client_request_id' => $clientRequestId];
+
+        if (isset($options['access_token'])) {
+            $sendOptions['access_token'] = $options['access_token'];
+        }
+
+        $response = $this->send('GET', $endpoint, $sendOptions, $context);
 
         return $this->toGraphResponse(
             action: 'list_policies',
@@ -89,10 +97,15 @@ public function listPolicies(string $policyType, array $options = []): GraphResp
     public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse
     {
         $endpoint = $this->endpointFor($policyType).'/'.urlencode($policyId);
-        $query = array_filter([
+        $queryInput = array_filter([
             '$select' => $options['select'] ?? null,
+            '$expand' => $options['expand'] ?? null,
         ], fn ($value) => $value !== null && $value !== '');
 
+        $sanitized = $this->contracts->sanitizeQuery($policyType, $queryInput);
+        $query = $sanitized['query'];
+        $warnings = $sanitized['warnings'];
+
         $context = $this->resolveContext($options);
         $clientRequestId = $options['client_request_id'] ?? (string) Str::uuid();
         $fullPath = $this->buildFullPath($endpoint, $query);
@@ -110,7 +123,7 @@ public function getPolicy(string $policyType, string $policyId, array $options =
 
         $response = $this->send('GET', $endpoint, ['query' => $query, 'client_request_id' => $clientRequestId], $context);
 
-        return $this->toGraphResponse(
+        $graphResponse = $this->toGraphResponse(
             action: 'get_policy',
             response: $response,
             transform: fn (array $json) => ['payload' => $json],
@@ -121,8 +134,52 @@ public function getPolicy(string $policyType, string $policyId, array $options =
                 'method' => 'GET',
                 'query' => $query ?: null,
                 'client_request_id' => $clientRequestId,
-            ]
+            ],
+            warnings: $warnings,
         );
+
+        if ($graphResponse->failed() && ! empty($query)) {
+            $fallbackQuery = array_filter($query, fn ($value, $key) => $key !== '$select' && $key !== '$expand', ARRAY_FILTER_USE_BOTH);
+            $fallbackPath = $this->buildFullPath($endpoint, $fallbackQuery);
+            $fallbackSendOptions = ['query' => $fallbackQuery, 'client_request_id' => $clientRequestId];
+
+            if (isset($options['access_token'])) {
+                $fallbackSendOptions['access_token'] = $options['access_token'];
+            }
+
+            $this->logger->logRequest('get_policy_fallback', [
+                'endpoint' => $endpoint,
+                'policy_type' => $policyType,
+                'policy_id' => $policyId,
+                'tenant' => $context['tenant'],
+                'full_path' => $fallbackPath,
+                'method' => 'GET',
+                'query' => $fallbackQuery ?: null,
+                'client_request_id' => $clientRequestId,
+            ]);
+
+            $fallbackResponse = $this->send('GET', $endpoint, $fallbackSendOptions, $context);
+
+            $graphResponse = $this->toGraphResponse(
+                action: 'get_policy',
+                response: $fallbackResponse,
+                transform: fn (array $json) => ['payload' => $json],
+                meta: [
+                    'tenant' => $context['tenant'] ?? null,
+                    'path' => $endpoint,
+                    'full_path' => $fallbackPath,
+                    'method' => 'GET',
+                    'query' => $fallbackQuery ?: null,
+                    'client_request_id' => $clientRequestId,
+                ],
+                warnings: array_values(array_unique(array_merge(
+                    $warnings,
+                    ['Capability fallback applied: removed $select/$expand for compatibility.']
+                ))),
+            );
+        }
+
+        return $graphResponse;
     }
 
     public function getOrganization(array $options = []): GraphResponse
@@ -409,7 +466,7 @@ private function send(string $method, string $path, array $options = [], array $
         return $response;
     }
 
-    private function toGraphResponse(string $action, Response $response, callable $transform, array $meta = []): GraphResponse
+    private function toGraphResponse(string $action, Response $response, callable $transform, array $meta = [], array $warnings = []): GraphResponse
     {
         $json = $response->json() ?? [];
         $meta = $this->responseMeta($response, $meta);
@@ -422,6 +479,7 @@ private function toGraphResponse(string $action, Response $response, callable $t
                 data: is_array($json) ? $json : [],
                 status: $response->status(),
                 errors: is_array($error) ? [$error] : [$error],
+                warnings: $warnings,
                 meta: $meta,
             );
 
@@ -434,6 +492,7 @@ private function toGraphResponse(string $action, Response $response, callable $t
             success: true,
             data: $transform(is_array($json) ? $json : []),
             status: $response->status(),
+            warnings: $warnings,
             meta: $meta,
         );
 

app/Services/Intune/BackupService.php

@@ -6,22 +6,16 @@
 use App\Models\BackupSet;
 use App\Models\Policy;
 use App\Models\Tenant;
-use App\Services\Graph\GraphClientInterface;
-use App\Services\Graph\GraphErrorMapper;
-use App\Services\Graph\GraphLogger;
 use Carbon\CarbonImmutable;
-use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\DB;
-use Throwable;
 
 class BackupService
 {
     public function __construct(
-        private readonly GraphClientInterface $graphClient,
-        private readonly GraphLogger $graphLogger,
         private readonly AuditLogger $auditLogger,
         private readonly VersionService $versionService,
         private readonly SnapshotValidator $snapshotValidator,
+        private readonly PolicySnapshotService $snapshotService,
     ) {}
 
     /**
@@ -192,63 +186,15 @@ private function resolveStatus(int $itemsCreated, array $failures): string
      */
     private function snapshotPolicy(Tenant $tenant, BackupSet $backupSet, Policy $policy, ?string $actorEmail = null): array
     {
-        $tenantIdentifier = $tenant->tenant_id ?? $tenant->external_id;
+        $snapshot = $this->snapshotService->fetch($tenant, $policy, $actorEmail);
 
-        $context = [
+        if (isset($snapshot['failure'])) {
-            'tenant' => $tenantIdentifier,
+            return [null, $snapshot['failure']];
-            'policy_type' => $policy->policy_type,
-            'policy_id' => $policy->external_id,
-        ];
-
-        $this->graphLogger->logRequest('get_policy', $context);
-
-        try {
-            $response = $this->graphClient->getPolicy($policy->policy_type, $policy->external_id, [
-                'tenant' => $tenantIdentifier,
-                'client_id' => $tenant->app_client_id,
-                'client_secret' => $tenant->app_client_secret,
-                'platform' => $policy->platform,
-            ]);
-        } catch (Throwable $throwable) {
-            $mapped = GraphErrorMapper::fromThrowable($throwable, $context);
-
-            return [
-                null,
-                [
-                    'policy_id' => $policy->id,
-                    'reason' => $mapped->getMessage(),
-                    'status' => $mapped->status,
-                ],
-            ];
         }
 
-        $this->graphLogger->logResponse('get_policy', $response, $context);
+        $payload = $snapshot['payload'];
-
+        $metadata = $snapshot['metadata'] ?? [];
-        $payload = $response->data['payload'] ?? $response->data;
+        $metadataWarnings = $snapshot['warnings'] ?? [];
-        $metadata = Arr::except($response->data, ['payload']);
-        $metadataWarnings = $metadata['warnings'] ?? [];
-
-        if ($response->failed()) {
-            $reason = $response->warnings[0] ?? 'Graph request failed';
-            $failure = [
-                'policy_id' => $policy->id,
-                'reason' => $reason,
-                'status' => $response->status,
-            ];
-
-            if (! config('graph.stub_on_failure')) {
-                return [null, $failure];
-            }
-
-            // Fallback to a stub payload for local/dev when Graph fails.
-            $payload = [
-                'id' => $policy->external_id,
-                'type' => $policy->policy_type,
-                'source' => 'stub',
-                'warning' => $reason,
-            ];
-            $metadataWarnings = $response->warnings ?? [$reason];
-        }
 
         $validation = $this->snapshotValidator->validate(is_array($payload) ? $payload : []);
         $metadataWarnings = array_merge($metadataWarnings, $validation['warnings']);

app/Services/Intune/PolicyNormalizer.php

@@ -8,21 +8,27 @@
 
 class PolicyNormalizer
 {
+    private const SETTINGS_CATALOG_MAX_ROWS = 1000;
+
+    private const SETTINGS_CATALOG_MAX_DEPTH = 8;
+
     /**
      * Normalize raw Intune snapshots into display-friendly blocks and warnings.
      */
     public function __construct(
         private readonly SnapshotValidator $validator,
+        private readonly SettingsCatalogDefinitionResolver $definitionResolver,
     ) {}
 
     /**
-     * @return array{status: string, settings: array<int, array<string, mixed>>, warnings: array<int, string>}
+     * @return array{status: string, settings: array<int, array<string, mixed>>, settings_table?: array<string, mixed>, warnings: array<int, string>, context?: string, record_id?: string}
      */
     public function normalize(?array $snapshot, string $policyType, ?string $platform = null): array
     {
         $snapshot = $snapshot ?? [];
         $resultWarnings = [];
         $status = 'success';
+        $settingsTable = null;
 
         $validation = $this->validator->validate($snapshot);
         $resultWarnings = array_merge($resultWarnings, $validation['warnings']);
@@ -48,9 +54,23 @@ public function normalize(?array $snapshot, string $policyType, ?string $platfor
         }
 
         if (isset($snapshot['settings']) && is_array($snapshot['settings'])) {
-            $settings[] = $this->normalizeSettingsCatalog($snapshot['settings']);
+            if ($policyType === 'settingsCatalogPolicy') {
+                $normalized = $this->buildSettingsCatalogSettingsTable($snapshot['settings']);
+                $settingsTable = $normalized['table'];
+                $resultWarnings = array_merge($resultWarnings, $normalized['warnings']);
+            } else {
+                $settings[] = $this->normalizeSettingsCatalog($snapshot['settings']);
+            }
         } elseif (isset($snapshot['settingsDelta']) && is_array($snapshot['settingsDelta'])) {
-            $settings[] = $this->normalizeSettingsCatalog($snapshot['settingsDelta'], 'Settings delta');
+            if ($policyType === 'settingsCatalogPolicy') {
+                $normalized = $this->buildSettingsCatalogSettingsTable($snapshot['settingsDelta'], 'Settings delta');
+                $settingsTable = $normalized['table'];
+                $resultWarnings = array_merge($resultWarnings, $normalized['warnings']);
+            } else {
+                $settings[] = $this->normalizeSettingsCatalog($snapshot['settingsDelta'], 'Settings delta');
+            }
+        } elseif ($policyType === 'settingsCatalogPolicy') {
+            $resultWarnings[] = 'Settings not hydrated for this Settings Catalog policy.';
         }
 
         $settings[] = $this->normalizeStandard($snapshot);
@@ -59,11 +79,17 @@ public function normalize(?array $snapshot, string $policyType, ?string $platfor
             $status = 'warning';
         }
 
-        return [
+        $result = [
             'status' => $status,
             'settings' => array_values(array_filter($settings)),
             'warnings' => array_values(array_unique($resultWarnings)),
         ];
+
+        if (is_array($settingsTable) && ! empty($settingsTable['rows'] ?? [])) {
+            $result['settings_table'] = $settingsTable;
+        }
+
+        return $result;
     }
 
     /**
@@ -76,6 +102,17 @@ public function flattenForDiff(?array $snapshot, string $policyType, ?string $pl
         $normalized = $this->normalize($snapshot ?? [], $policyType, $platform);
         $map = [];
 
+        if (isset($normalized['settings_table']['rows']) && is_array($normalized['settings_table']['rows'])) {
+            foreach ($normalized['settings_table']['rows'] as $row) {
+                if (! is_array($row)) {
+                    continue;
+                }
+
+                $key = $row['path'] ?? $row['definition'] ?? 'entry';
+                $map[$key] = $row['value'] ?? null;
+            }
+        }
+
         foreach ($normalized['settings'] as $block) {
             if (($block['type'] ?? null) === 'table') {
                 foreach ($block['rows'] ?? [] as $row) {
@@ -158,6 +195,289 @@ private function normalizeSettingsCatalog(array $settings, string $title = 'Sett
         ];
     }
 
+    /**
+     * @param  array<int, mixed>  $settings
+     * @return array{table: array<string, mixed>, warnings: array<int, string>}
+     */
+    private function buildSettingsCatalogSettingsTable(array $settings, string $title = 'Settings'): array
+    {
+        $flattened = $this->flattenSettingsCatalogSettingInstances($settings);
+
+        return [
+            'table' => [
+                'title' => $title,
+                'rows' => $flattened['rows'],
+            ],
+            'warnings' => $flattened['warnings'],
+        ];
+    }
+
+    /**
+     * @param  array<int, mixed>  $settings
+     * @return array{rows: array<int, array<string, mixed>>, warnings: array<int, string>}
+     */
+    private function flattenSettingsCatalogSettingInstances(array $settings): array
+    {
+        $rows = [];
+        $warnings = [];
+        $rowCount = 0;
+        $warnedDepthLimit = false;
+        $warnedRowLimit = false;
+
+        $walk = function (array $nodes, array $pathParts, int $depth) use (
+            &$walk,
+            &$rows,
+            &$warnings,
+            &$rowCount,
+            &$warnedDepthLimit,
+            &$warnedRowLimit
+        ): void {
+            if ($rowCount >= self::SETTINGS_CATALOG_MAX_ROWS) {
+                if (! $warnedRowLimit) {
+                    $warnings[] = sprintf('Settings truncated after %d rows.', self::SETTINGS_CATALOG_MAX_ROWS);
+                    $warnedRowLimit = true;
+                }
+
+                return;
+            }
+
+            if ($depth > self::SETTINGS_CATALOG_MAX_DEPTH) {
+                if (! $warnedDepthLimit) {
+                    $warnings[] = sprintf('Settings nesting truncated after depth %d.', self::SETTINGS_CATALOG_MAX_DEPTH);
+                    $warnedDepthLimit = true;
+                }
+
+                return;
+            }
+
+            foreach ($nodes as $node) {
+                if ($rowCount >= self::SETTINGS_CATALOG_MAX_ROWS) {
+                    break;
+                }
+
+                if (! is_array($node)) {
+                    continue;
+                }
+
+                $instance = $this->extractSettingsCatalogSettingInstance($node);
+                $definitionId = $this->extractSettingsCatalogDefinitionId($node, $instance);
+                $instanceType = is_array($instance) ? ($instance['@odata.type'] ?? $node['@odata.type'] ?? null) : ($node['@odata.type'] ?? null);
+                $instanceType = $this->formatSettingsCatalogInstanceType(is_string($instanceType) ? ltrim($instanceType, '#') : null);
+
+                $currentPathParts = array_merge($pathParts, [$definitionId]);
+                $path = implode(' > ', $currentPathParts);
+
+                $value = $this->extractSettingsCatalogValue($node, $instance);
+
+                $rows[] = [
+                    'definition' => $definitionId,
+                    'type' => $instanceType ?? '-',
+                    'value' => $this->stringifySettingsCatalogValue($value),
+                    'path' => $path,
+                    'raw' => $this->pruneSettingsCatalogRaw($instance ?? $node),
+                ];
+
+                $rowCount++;
+
+                if (! is_array($instance)) {
+                    continue;
+                }
+
+                $nested = $this->extractSettingsCatalogChildren($instance);
+
+                if (! empty($nested)) {
+                    $walk($nested, $currentPathParts, $depth + 1);
+                }
+
+                if ($this->isSettingsCatalogGroupSettingCollectionInstance($instance)) {
+                    $collections = $instance['groupSettingCollectionValue'] ?? [];
+
+                    if (! is_array($collections)) {
+                        continue;
+                    }
+
+                    foreach (array_values($collections) as $index => $collection) {
+                        if ($rowCount >= self::SETTINGS_CATALOG_MAX_ROWS) {
+                            break;
+                        }
+
+                        if (! is_array($collection)) {
+                            continue;
+                        }
+
+                        $children = $collection['children'] ?? [];
+
+                        if (! is_array($children) || empty($children)) {
+                            continue;
+                        }
+
+                        $walk($children, array_merge($currentPathParts, ['['.($index + 1).']']), $depth + 1);
+                    }
+                }
+            }
+        };
+
+        $walk($settings, [], 1);
+
+        return [
+            'rows' => array_slice($rows, 0, self::SETTINGS_CATALOG_MAX_ROWS),
+            'warnings' => $warnings,
+        ];
+    }
+
+    private function extractSettingsCatalogSettingInstance(array $setting): ?array
+    {
+        $instance = $setting['settingInstance'] ?? null;
+
+        if (is_array($instance)) {
+            return $instance;
+        }
+
+        if (isset($setting['@odata.type']) && (isset($setting['settingDefinitionId']) || isset($setting['definitionId']))) {
+            return $setting;
+        }
+
+        return null;
+    }
+
+    private function extractSettingsCatalogDefinitionId(array $setting, ?array $instance): string
+    {
+        $candidates = [
+            $setting['definitionId'] ?? null,
+            $setting['settingDefinitionId'] ?? null,
+            $setting['name'] ?? null,
+            $setting['displayName'] ?? null,
+            $instance['settingDefinitionId'] ?? null,
+            $instance['definitionId'] ?? null,
+        ];
+
+        foreach ($candidates as $candidate) {
+            if (is_string($candidate) && $candidate !== '') {
+                return $candidate;
+            }
+        }
+
+        return 'setting';
+    }
+
+    private function formatSettingsCatalogInstanceType(?string $type): ?string
+    {
+        if (! $type) {
+            return null;
+        }
+
+        $type = Str::afterLast($type, '.');
+
+        foreach (['deviceManagementConfiguration', 'deviceManagement'] as $prefix) {
+            if (Str::startsWith($type, $prefix)) {
+                $type = substr($type, strlen($prefix));
+
+                break;
+            }
+        }
+
+        return $type !== '' ? $type : null;
+    }
+
+    private function isSettingsCatalogGroupSettingCollectionInstance(array $instance): bool
+    {
+        $type = $instance['@odata.type'] ?? null;
+
+        if (! is_string($type)) {
+            return false;
+        }
+
+        return Str::contains($type, 'GroupSettingCollectionInstance', ignoreCase: true);
+    }
+
+    /**
+     * @return array<int, mixed>
+     */
+    private function extractSettingsCatalogChildren(array $instance): array
+    {
+        foreach (['children', 'groupSettingValue.children'] as $path) {
+            $children = Arr::get($instance, $path);
+
+            if (is_array($children) && ! empty($children)) {
+                return $children;
+            }
+        }
+
+        return [];
+    }
+
+    private function extractSettingsCatalogValue(array $setting, ?array $instance): mixed
+    {
+        if ($instance === null) {
+            return $setting['value'] ?? null;
+        }
+
+        $type = $instance['@odata.type'] ?? null;
+        $type = is_string($type) ? $type : '';
+
+        if (Str::contains($type, 'SimpleSettingInstance', ignoreCase: true)) {
+            $simple = $instance['simpleSettingValue'] ?? null;
+
+            if (is_array($simple)) {
+                return $simple['value'] ?? $simple;
+            }
+
+            return $simple;
+        }
+
+        if (Str::contains($type, 'ChoiceSettingInstance', ignoreCase: true)) {
+            $choice = $instance['choiceSettingValue'] ?? null;
+
+            if (is_array($choice)) {
+                return $choice['value'] ?? $choice;
+            }
+
+            return $choice;
+        }
+
+        if ($this->isSettingsCatalogGroupSettingCollectionInstance($instance) || Str::contains($type, 'GroupSettingInstance', ignoreCase: true)) {
+            return '(group)';
+        }
+
+        $fallback = $instance;
+        unset($fallback['children']);
+
+        return $fallback;
+    }
+
+    private function stringifySettingsCatalogValue(mixed $value): string
+    {
+        if ($value === null) {
+            return '-';
+        }
+
+        if (is_bool($value)) {
+            return $value ? 'true' : 'false';
+        }
+
+        if (is_scalar($value)) {
+            return (string) $value;
+        }
+
+        if (is_array($value)) {
+            return (string) json_encode($value, JSON_PRETTY_PRINT);
+        }
+
+        return (string) $value;
+    }
+
+    private function pruneSettingsCatalogRaw(mixed $raw): mixed
+    {
+        if (! is_array($raw)) {
+            return $raw;
+        }
+
+        $pruned = $raw;
+        unset($pruned['children'], $pruned['groupSettingCollectionValue']);
+
+        return $pruned;
+    }
+
     private function normalizeStandard(array $snapshot): array
     {
         $metadataKeys = [
@@ -197,4 +517,268 @@ private function normalizeStandard(array $snapshot): array
             'entries' => $entries,
         ];
     }
+
+    /**
+     * Normalize Settings Catalog policy with grouped, readable settings (T011-T014).
+     *
+     * @param  array<int, mixed>  $settings
+     * @return array{type: string, groups: array<int, array<string, mixed>>}
+     */
+    public function normalizeSettingsCatalogGrouped(array $settings): array
+    {
+        // Extract all definition IDs
+        $definitionIds = $this->extractAllDefinitionIds($settings);
+
+        // Resolve definitions
+        $definitions = $this->definitionResolver->resolve($definitionIds);
+
+        // Flatten settings
+        $flattened = $this->flattenSettingsCatalogForGrouping($settings);
+
+        // Group by category
+        $groups = $this->groupSettingsByCategory($flattened, $definitions);
+
+        return [
+            'type' => 'settings_catalog_grouped',
+            'groups' => $groups,
+        ];
+    }
+
+    /**
+     * Extract all definition IDs from settings array recursively.
+     */
+    private function extractAllDefinitionIds(array $settings): array
+    {
+        $ids = [];
+
+        foreach ($settings as $setting) {
+            // Top-level settings have settingInstance wrapper
+            if (isset($setting['settingInstance']['settingDefinitionId'])) {
+                $ids[] = $setting['settingInstance']['settingDefinitionId'];
+                $instance = $setting['settingInstance'];
+            }
+            // Nested children have settingDefinitionId directly (they ARE the instance)
+            elseif (isset($setting['settingDefinitionId'])) {
+                $ids[] = $setting['settingDefinitionId'];
+                $instance = $setting;
+            } else {
+                continue;
+            }
+
+            // Handle nested children in group collections
+            if (isset($instance['groupSettingCollectionValue'])) {
+                foreach ($instance['groupSettingCollectionValue'] as $group) {
+                    if (isset($group['children']) && is_array($group['children'])) {
+                        $childIds = $this->extractAllDefinitionIds($group['children']);
+                        $ids = array_merge($ids, $childIds);
+                    }
+                }
+            }
+        }
+
+        return array_unique($ids);
+    }
+
+    /**
+     * Flatten settings for grouping with value formatting.
+     */
+    private function flattenSettingsCatalogForGrouping(array $settings): array
+    {
+        $rows = [];
+
+        $walk = function (array $nodes, array $pathParts) use (&$walk, &$rows): void {
+            foreach ($nodes as $node) {
+                if (! is_array($node)) {
+                    continue;
+                }
+
+                $instance = $this->extractSettingsCatalogSettingInstance($node);
+                $definitionId = $this->extractSettingsCatalogDefinitionId($node, $instance);
+                $value = $this->extractSettingsCatalogValue($node, $instance);
+                $isGroupCollection = $this->isSettingsCatalogGroupSettingCollectionInstance($instance);
+
+                // Only add to rows if NOT a group collection (those are containers)
+                if (! $isGroupCollection) {
+                    $rows[] = [
+                        'definition_id' => $definitionId,
+                        'value_raw' => $value,
+                        'value_display' => $this->formatSettingsCatalogValue($value),
+                        'instance_type' => is_array($instance) ? ($instance['@odata.type'] ?? null) : null,
+                    ];
+                }
+
+                // Handle nested children
+                if (is_array($instance)) {
+                    $nested = $this->extractSettingsCatalogChildren($instance);
+                    if (! empty($nested)) {
+                        $walk($nested, array_merge($pathParts, [$definitionId]));
+                    }
+
+                    // Handle group collections
+                    if ($this->isSettingsCatalogGroupSettingCollectionInstance($instance)) {
+                        $collections = $instance['groupSettingCollectionValue'] ?? [];
+                        if (is_array($collections)) {
+                            foreach ($collections as $collection) {
+                                if (isset($collection['children']) && is_array($collection['children'])) {
+                                    $walk($collection['children'], array_merge($pathParts, [$definitionId]));
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+
+        $walk($settings, []);
+
+        return $rows;
+    }
+
+    /**
+     * Format setting value for display (T012).
+     */
+    private function formatSettingsCatalogValue(mixed $value): string
+    {
+        if (is_bool($value)) {
+            return $value ? 'Enabled' : 'Disabled';
+        }
+
+        if (is_int($value)) {
+            return number_format($value);
+        }
+
+        if (is_string($value)) {
+            // Remove {tenantid} placeholder
+            $value = str_replace(['{tenantid}', '_tenantid_'], ['', '_'], $value);
+            $value = preg_replace('/_+/', '_', $value);
+
+            // Extract choice label from choice values (last meaningful part)
+            // Example: "device_vendor_msft_...lowercaseletters_0" -> "Not Required (0)"
+            if (str_contains($value, 'device_vendor_msft') || str_contains($value, '#microsoft.graph')) {
+                $parts = explode('_', $value);
+                $lastPart = end($parts);
+
+                // Check for boolean-like values
+                if (in_array(strtolower($lastPart), ['true', 'false'])) {
+                    return strtolower($lastPart) === 'true' ? 'Enabled' : 'Disabled';
+                }
+
+                // If last part is just a number, take second-to-last too
+                if (is_numeric($lastPart) && count($parts) > 1) {
+                    $secondLast = $parts[count($parts) - 2];
+                    // Map common values
+                    $mapping = [
+                        'lowercaseletters' => 'Lowercase Letters',
+                        'uppercaseletters' => 'Uppercase Letters',
+                        'specialcharacters' => 'Special Characters',
+                        'digits' => 'Digits',
+                    ];
+                    $label = $mapping[strtolower($secondLast)] ?? Str::title($secondLast);
+
+                    return $label.': '.$lastPart;
+                }
+
+                return Str::title($lastPart);
+            }
+
+            // Truncate long strings
+            return Str::limit($value, 100);
+        }
+
+        if (is_array($value)) {
+            return json_encode($value);
+        }
+
+        return (string) $value;
+    }
+
+    /**
+     * Group settings by category (T013).
+     */
+    private function groupSettingsByCategory(array $rows, array $definitions): array
+    {
+        $grouped = [];
+
+        foreach ($rows as $row) {
+            $definitionId = $row['definition_id'];
+            $definition = $definitions[$definitionId] ?? null;
+
+            // Determine category
+            $categoryId = $definition['categoryId'] ?? $this->extractCategoryFromDefinitionId($definitionId);
+            $categoryTitle = $this->formatCategoryTitle($categoryId);
+
+            if (! isset($grouped[$categoryId])) {
+                $grouped[$categoryId] = [
+                    'title' => $categoryTitle,
+                    'description' => null,
+                    'settings' => [],
+                ];
+            }
+
+            $grouped[$categoryId]['settings'][] = [
+                'label' => $definition['displayName'] ?? $row['definition_id'],
+                'value' => $row['value_display'], // Primary value for display
+                'value_display' => $row['value_display'],
+                'value_raw' => $row['value_raw'],
+                'help_text' => $definition['helpText'] ?? $definition['description'] ?? null,
+                'definition_id' => $definitionId,
+                'instance_type' => $row['instance_type'],
+                'is_fallback' => $definition['isFallback'] ?? false,
+            ];
+        }
+
+        // Sort groups by title
+        uasort($grouped, fn ($a, $b) => strcmp($a['title'], $b['title']));
+
+        // Sort settings within each group by label for stable ordering
+        foreach ($grouped as $cid => $g) {
+            if (isset($g['settings']) && is_array($g['settings'])) {
+                usort($g['settings'], function ($a, $b) {
+                    return strcmp(strtolower($a['label'] ?? ''), strtolower($b['label'] ?? ''));
+                });
+
+                $grouped[$cid]['settings'] = $g['settings'];
+            }
+        }
+
+        return array_values($grouped);
+    }
+
+    /**
+     * Extract category from definition ID (fallback grouping).
+     */
+    private function extractCategoryFromDefinitionId(string $definitionId): string
+    {
+        $parts = explode('_', $definitionId);
+
+        // Use first 2-3 segments as category
+        return implode('_', array_slice($parts, 0, min(3, count($parts))));
+    }
+
+    /**
+     * Format category ID into readable title.
+     */
+    private function formatCategoryTitle(string $categoryId): string
+    {
+        // Try to prettify known patterns
+        if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-/i', $categoryId)) {
+            // It's a UUID - likely a category ID from Graph
+            return 'Additional Settings';
+        }
+
+        // Clean up common prefixes
+        $title = str_replace('device_vendor_msft_', '', $categoryId);
+        $title = Str::title(str_replace('_', ' ', $title));
+
+        // Known mappings
+        $mappings = [
+            'Passportforwork' => 'Windows Hello for Business',
+        ];
+
+        foreach ($mappings as $search => $replace) {
+            $title = str_replace($search, $replace, $title);
+        }
+
+        return $title;
+    }
 }

app/Services/Intune/PolicySnapshotService.php

@@ -0,0 +1,217 @@
+<?php
+
+namespace App\Services\Intune;
+
+use App\Models\Policy;
+use App\Models\Tenant;
+use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphContractRegistry;
+use App\Services\Graph\GraphErrorMapper;
+use App\Services\Graph\GraphLogger;
+use Illuminate\Support\Arr;
+use Throwable;
+
+class PolicySnapshotService
+{
+    public function __construct(
+        private readonly GraphClientInterface $graphClient,
+        private readonly GraphLogger $graphLogger,
+        private readonly GraphContractRegistry $contracts,
+        private readonly SnapshotValidator $snapshotValidator,
+        private readonly SettingsCatalogDefinitionResolver $definitionResolver,
+    ) {}
+
+    /**
+     * Fetch a policy snapshot from Graph (with optional hydration) for backup/version capture.
+     *
+     * @return array{payload:array,metadata:array,warnings:array}|array{failure:array}
+     */
+    public function fetch(Tenant $tenant, Policy $policy, ?string $actorEmail = null): array
+    {
+        $tenantIdentifier = $tenant->tenant_id ?? $tenant->external_id;
+
+        $context = [
+            'tenant' => $tenantIdentifier,
+            'policy_type' => $policy->policy_type,
+            'policy_id' => $policy->external_id,
+        ];
+
+        $this->graphLogger->logRequest('get_policy', $context);
+
+        try {
+            $response = $this->graphClient->getPolicy($policy->policy_type, $policy->external_id, [
+                'tenant' => $tenantIdentifier,
+                'client_id' => $tenant->app_client_id,
+                'client_secret' => $tenant->app_client_secret,
+                'platform' => $policy->platform,
+            ]);
+        } catch (Throwable $throwable) {
+            $mapped = GraphErrorMapper::fromThrowable($throwable, $context);
+
+            return [
+                'failure' => [
+                    'policy_id' => $policy->id,
+                    'reason' => $mapped->getMessage(),
+                    'status' => $mapped->status,
+                ],
+            ];
+        }
+
+        $this->graphLogger->logResponse('get_policy', $response, $context);
+
+        $payload = $response->data['payload'] ?? $response->data;
+        $metadata = Arr::except($response->data, ['payload']);
+        $metadataWarnings = $metadata['warnings'] ?? [];
+
+        if ($policy->policy_type === 'settingsCatalogPolicy') {
+            [$payload, $metadata] = $this->hydrateSettingsCatalog(
+                tenantIdentifier: $tenantIdentifier,
+                tenant: $tenant,
+                policyId: $policy->external_id,
+                payload: is_array($payload) ? $payload : [],
+                metadata: $metadata
+            );
+        }
+
+        if ($response->failed()) {
+            $reason = $response->warnings[0] ?? 'Graph request failed';
+            $failure = [
+                'policy_id' => $policy->id,
+                'reason' => $reason,
+                'status' => $response->status,
+            ];
+
+            if (! config('graph.stub_on_failure')) {
+                return ['failure' => $failure];
+            }
+
+            $payload = [
+                'id' => $policy->external_id,
+                'type' => $policy->policy_type,
+                'source' => 'stub',
+                'warning' => $reason,
+            ];
+            $metadataWarnings = $response->warnings ?? [$reason];
+        }
+
+        $validation = $this->snapshotValidator->validate(is_array($payload) ? $payload : []);
+        $metadataWarnings = array_merge($metadataWarnings, $validation['warnings']);
+
+        $odataWarning = Policy::odataTypeWarning(is_array($payload) ? $payload : [], $policy->policy_type, $policy->platform);
+
+        if ($odataWarning) {
+            $metadataWarnings[] = $odataWarning;
+        }
+
+        if (! empty($metadataWarnings)) {
+            $metadata['warnings'] = array_values(array_unique($metadataWarnings));
+        }
+
+        return [
+            'payload' => is_array($payload) ? $payload : [],
+            'metadata' => $metadata,
+            'warnings' => $metadataWarnings,
+        ];
+    }
+
+    /**
+     * Hydrate settings catalog policies with configuration settings subresource.
+     *
+     * @return array{0:array,1:array}
+     */
+    private function hydrateSettingsCatalog(string $tenantIdentifier, Tenant $tenant, string $policyId, array $payload, array $metadata): array
+    {
+        $strategy = $this->contracts->memberHydrationStrategy('settingsCatalogPolicy');
+        $settingsPath = $this->contracts->subresourceSettingsPath('settingsCatalogPolicy', $policyId);
+
+        if ($strategy !== 'subresource_settings' || ! $settingsPath) {
+            return [$payload, $metadata];
+        }
+
+        $settings = [];
+        $nextPath = $settingsPath;
+        $hydrationStatus = 'complete';
+
+        while ($nextPath) {
+            $response = $this->graphClient->request('GET', $nextPath, [
+                'tenant' => $tenantIdentifier,
+                'client_id' => $tenant->app_client_id,
+                'client_secret' => $tenant->app_client_secret,
+            ]);
+
+            if ($response->failed()) {
+                $hydrationStatus = 'failed';
+
+                break;
+            }
+
+            $data = $response->data;
+            $pageItems = $data['value'] ?? (is_array($data) ? $data : []);
+            $settings = array_merge($settings, $pageItems);
+            $nextLink = $data['@odata.nextLink'] ?? null;
+
+            if (! $nextLink) {
+                break;
+            }
+
+            $nextPath = $this->stripGraphBaseUrl((string) $nextLink);
+        }
+
+        if (! empty($settings)) {
+            $payload['settings'] = $settings;
+
+            // Extract definition IDs and warm cache (T008-T010)
+            $definitionIds = $this->extractDefinitionIds($settings);
+            $metadata['definition_count'] = count($definitionIds);
+
+            // Warm cache for definitions (non-blocking)
+            $this->definitionResolver->warmCache($definitionIds);
+            $metadata['definitions_cached'] = true;
+        }
+
+        $metadata['settings_hydration'] = $hydrationStatus;
+
+        return [$payload, $metadata];
+    }
+
+    /**
+     * Extract all settingDefinitionId from settings array, including nested children.
+     */
+    private function extractDefinitionIds(array $settings): array
+    {
+        $definitionIds = [];
+
+        foreach ($settings as $setting) {
+            // Extract definition ID from settingInstance
+            if (isset($setting['settingInstance']['settingDefinitionId'])) {
+                $definitionIds[] = $setting['settingInstance']['settingDefinitionId'];
+            }
+
+            // Handle groupSettingCollectionInstance with children
+            if (isset($setting['settingInstance']['@odata.type']) &&
+                str_contains($setting['settingInstance']['@odata.type'], 'groupSettingCollectionInstance')) {
+                if (isset($setting['settingInstance']['groupSettingCollectionValue'])) {
+                    foreach ($setting['settingInstance']['groupSettingCollectionValue'] as $group) {
+                        if (isset($group['children'])) {
+                            $childIds = $this->extractDefinitionIds($group['children']);
+                            $definitionIds = array_merge($definitionIds, $childIds);
+                        }
+                    }
+                }
+            }
+        }
+
+        return array_unique($definitionIds);
+    }
+
+    private function stripGraphBaseUrl(string $nextLink): string
+    {
+        $base = rtrim(config('graph.base_url', 'https://graph.microsoft.com'), '/').'/'.trim(config('graph.version', 'beta'), '/');
+
+        if (str_starts_with($nextLink, $base)) {
+            return ltrim(substr($nextLink, strlen($base)), '/');
+        }
+
+        return ltrim($nextLink, '/');
+    }
+}

app/Services/Intune/PolicySyncService.php

@@ -77,6 +77,16 @@ public function syncPolicies(Tenant $tenant, ?array $supportedTypes = null): arr
                 $displayName = $policyData['displayName'] ?? $policyData['name'] ?? 'Unnamed policy';
                 $policyPlatform = $platform ?? ($policyData['platform'] ?? null);
 
+                $existingWithDifferentType = Policy::query()
+                    ->where('tenant_id', $tenant->id)
+                    ->where('external_id', $externalId)
+                    ->where('policy_type', '!=', $policyType)
+                    ->exists();
+
+                if ($existingWithDifferentType) {
+                    continue;
+                }
+
                 $policy = Policy::updateOrCreate(
                     [
                         'tenant_id' => $tenant->id,

app/Services/Intune/RestoreService.php

@@ -8,9 +8,11 @@
 use App\Models\RestoreRun;
 use App\Models\Tenant;
 use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphContractRegistry;
 use App\Services\Graph\GraphErrorMapper;
 use App\Services\Graph\GraphLogger;
 use Carbon\CarbonImmutable;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 use Throwable;
 
@@ -22,6 +24,7 @@ public function __construct(
         private readonly AuditLogger $auditLogger,
         private readonly VersionService $versionService,
         private readonly SnapshotValidator $snapshotValidator,
+        private readonly GraphContractRegistry $contracts,
     ) {}
 
     /**
@@ -90,7 +93,7 @@ public function execute(
         ]);
 
         $results = [];
-        $failures = 0;
+        $hardFailures = 0;
 
         foreach ($items as $item) {
             $context = [
@@ -116,7 +119,7 @@ public function execute(
                     ) ?? 'Snapshot type mismatch',
                     'code' => 'odata_mismatch',
                 ];
-                $failures++;
+                $hardFailures++;
 
                 continue;
             }
@@ -130,27 +133,67 @@ public function execute(
             $this->graphLogger->logRequest('apply_policy', $context);
 
             try {
-                $payload = $this->sanitizePayload($item->payload);
+                $originalPayload = is_array($item->payload) ? $item->payload : [];
 
-                $response = $this->graphClient->applyPolicy(
+                // sanitize high-level fields according to contract
-                    $item->policy_type,
+                $payload = $this->contracts->sanitizeUpdatePayload($item->policy_type, $originalPayload);
-                    $item->policy_identifier,
+
-                    $payload,
+                $graphOptions = [
-                    [
+                    'tenant' => $tenantIdentifier,
-                        'tenant' => $tenantIdentifier,
+                    'client_id' => $tenant->app_client_id,
-                        'client_id' => $tenant->app_client_id,
+                    'client_secret' => $tenant->app_client_secret,
-                        'client_secret' => $tenant->app_client_secret,
+                    'platform' => $item->platform,
-                        'platform' => $item->platform,
+                ];
-                    ]
+
-                );
+                $settingsApply = null;
+                $itemStatus = 'applied';
+
+                if ($item->policy_type === 'settingsCatalogPolicy') {
+                    $settings = $this->extractSettingsCatalogSettings($originalPayload);
+                    $policyPayload = $this->stripSettingsFromPayload($payload);
+
+                    $response = $this->graphClient->applyPolicy(
+                        $item->policy_type,
+                        $item->policy_identifier,
+                        $policyPayload,
+                        $graphOptions
+                    );
+
+                    if ($response->successful() && $settings !== []) {
+                        [$settingsApply, $itemStatus] = $this->applySettingsCatalogPolicySettings(
+                            policyId: $item->policy_identifier,
+                            settings: $settings,
+                            graphOptions: $graphOptions,
+                            context: $context,
+                        );
+                    } elseif ($settings !== []) {
+                        $settingsApply = [
+                            'total' => count($settings),
+                            'applied' => 0,
+                            'failed' => count($settings),
+                            'manual_required' => 0,
+                            'issues' => [],
+                        ];
+                    }
+                } else {
+                    $response = $this->graphClient->applyPolicy(
+                        $item->policy_type,
+                        $item->policy_identifier,
+                        $payload,
+                        $graphOptions
+                    );
+                }
             } catch (Throwable $throwable) {
                 $mapped = GraphErrorMapper::fromThrowable($throwable, $context);
+
                 $results[] = $context + [
                     'status' => 'failed',
                     'reason' => $mapped->getMessage(),
                     'code' => $mapped->status,
+                    'graph_error_message' => $mapped->getMessage(),
+                    'graph_error_code' => $mapped->status,
                 ];
-                $failures++;
+                $hardFailures++;
 
                 continue;
             }
@@ -162,21 +205,37 @@ public function execute(
                     'status' => 'failed',
                     'reason' => 'Graph apply failed',
                     'code' => $response->status,
+                    'graph_error_message' => $response->meta['error_message'] ?? null,
+                    'graph_error_code' => $response->meta['error_code'] ?? null,
+                    'graph_request_id' => $response->meta['request_id'] ?? null,
+                    'graph_client_request_id' => $response->meta['client_request_id'] ?? null,
                 ];
-                $failures++;
+                $hardFailures++;
 
                 continue;
             }
 
-            $results[] = $context + ['status' => 'applied'];
+            $result = $context + ['status' => $itemStatus];
+
+            if ($settingsApply !== null) {
+                $result['settings_apply'] = $settingsApply;
+            }
+
+            if ($itemStatus !== 'applied') {
+                $result['reason'] = 'Some settings require attention';
+            }
+
+            $results[] = $result;
+
+            $appliedPolicyId = $item->policy_identifier;
 
             $policy = Policy::query()
                 ->where('tenant_id', $tenant->id)
-                ->where('external_id', $item->policy_identifier)
+                ->where('external_id', $appliedPolicyId)
                 ->where('policy_type', $item->policy_type)
                 ->first();
 
-            if ($policy) {
+            if ($policy && $itemStatus === 'applied') {
                 $this->versionService->captureVersion(
                     policy: $policy,
                     payload: $item->payload,
@@ -190,11 +249,15 @@ public function execute(
             }
         }
 
+        $resultStatuses = collect($results)->pluck('status')->all();
+        $nonApplied = collect($resultStatuses)->filter(fn (string $status) => $status !== 'applied' && $status !== 'dry_run')->count();
+        $allHardFailed = count($results) > 0 && $hardFailures === count($results);
+
         $status = $dryRun
             ? 'previewed'
             : (match (true) {
-                $failures === count($results) => 'failed',
+                $allHardFailed => 'failed',
-                $failures > 0 => 'partial',
+                $nonApplied > 0 => 'partial',
                 default => 'completed',
             });
 
@@ -203,7 +266,8 @@ public function execute(
             'results' => $results,
             'completed_at' => CarbonImmutable::now(),
             'metadata' => [
-                'failed' => $failures,
+                'failed' => $hardFailures,
+                'non_applied' => $nonApplied,
                 'total' => count($results),
             ],
         ]);
@@ -285,6 +349,168 @@ private function sanitizePayload(array $payload): array
         return $clean;
     }
 
+    /**
+     * @return array<int, mixed>
+     */
+    private function extractSettingsCatalogSettings(array $payload): array
+    {
+        foreach ($payload as $key => $value) {
+            if (strtolower((string) $key) !== 'settings') {
+                continue;
+            }
+
+            return is_array($value) ? $value : [];
+        }
+
+        return [];
+    }
+
+    private function stripSettingsFromPayload(array $payload): array
+    {
+        foreach (array_keys($payload) as $key) {
+            if (strtolower((string) $key) === 'settings') {
+                unset($payload[$key]);
+            }
+        }
+
+        return $payload;
+    }
+
+    private function resolveSettingsCatalogSettingId(array $setting): ?string
+    {
+        foreach ($setting as $key => $value) {
+            if (strtolower((string) $key) !== 'id') {
+                continue;
+            }
+
+            if (is_string($value) || is_int($value)) {
+                return (string) $value;
+            }
+
+            return null;
+        }
+
+        return null;
+    }
+
+    /**
+     * @param  array<int, mixed>  $settings
+     * @param  array<string, mixed>  $graphOptions
+     * @param  array<string, mixed>  $context
+     * @return array{0: array{total:int,applied:int,failed:int,manual_required:int,issues:array<int,array<string,mixed>>}, 1: string}
+     */
+    private function applySettingsCatalogPolicySettings(
+        string $policyId,
+        array $settings,
+        array $graphOptions,
+        array $context,
+    ): array {
+        $method = $this->contracts->settingsWriteMethod('settingsCatalogPolicy');
+        $issues = [];
+        $applied = 0;
+        $failed = 0;
+        $manualRequired = 0;
+
+        foreach ($settings as $setting) {
+            if (! is_array($setting)) {
+                continue;
+            }
+
+            $settingId = $this->resolveSettingsCatalogSettingId($setting);
+            $path = ($method && $settingId)
+                ? $this->contracts->settingsWritePath('settingsCatalogPolicy', $policyId, $settingId)
+                : null;
+
+            if (! $method || ! $path || ! $settingId) {
+                $manualRequired++;
+                $issues[] = array_filter([
+                    'setting_id' => $settingId,
+                    'status' => 'manual_required',
+                    'reason' => ! $settingId
+                        ? 'Setting id missing (cannot apply automatically).'
+                        : 'Settings write contract is not configured (cannot apply automatically).',
+                ], static fn ($value) => $value !== null && $value !== '');
+
+                continue;
+            }
+
+            $sanitized = $this->contracts->sanitizeSettingsApplyPayload('settingsCatalogPolicy', [$setting])[0] ?? null;
+
+            if (! is_array($sanitized) || $sanitized === []) {
+                $manualRequired++;
+                $issues[] = [
+                    'setting_id' => $settingId,
+                    'status' => 'manual_required',
+                    'reason' => 'Setting payload could not be sanitized (empty payload).',
+                ];
+
+                continue;
+            }
+
+            $this->graphLogger->logRequest('apply_setting', $context + [
+                'setting_id' => $settingId,
+                'endpoint' => $path,
+                'method' => $method,
+            ]);
+
+            $response = $this->graphClient->request($method, $path, ['json' => $sanitized] + Arr::except($graphOptions, ['platform']));
+
+            $this->graphLogger->logResponse('apply_setting', $response, $context + [
+                'setting_id' => $settingId,
+                'endpoint' => $path,
+                'method' => $method,
+            ]);
+
+            if ($response->successful()) {
+                $applied++;
+
+                continue;
+            }
+
+            if ($response->status === 404) {
+                $manualRequired++;
+                $issues[] = [
+                    'setting_id' => $settingId,
+                    'status' => 'manual_required',
+                    'reason' => 'Setting not found on target policy (404).',
+                    'graph_error_message' => $response->meta['error_message'] ?? null,
+                    'graph_error_code' => $response->meta['error_code'] ?? null,
+                    'graph_request_id' => $response->meta['request_id'] ?? null,
+                    'graph_client_request_id' => $response->meta['client_request_id'] ?? null,
+                ];
+
+                continue;
+            }
+
+            $failed++;
+            $issues[] = [
+                'setting_id' => $settingId,
+                'status' => 'failed',
+                'reason' => 'Graph apply failed',
+                'graph_error_message' => $response->meta['error_message'] ?? null,
+                'graph_error_code' => $response->meta['error_code'] ?? null,
+                'graph_request_id' => $response->meta['request_id'] ?? null,
+                'graph_client_request_id' => $response->meta['client_request_id'] ?? null,
+            ];
+        }
+
+        $summary = [
+            'total' => count($settings),
+            'applied' => $applied,
+            'failed' => $failed,
+            'manual_required' => $manualRequired,
+            'issues' => $issues,
+        ];
+
+        $status = match (true) {
+            $manualRequired > 0 => 'manual_required',
+            $failed > 0 => 'partial',
+            default => 'applied',
+        };
+
+        return [$summary, $status];
+    }
+
     private function assertActiveContext(Tenant $tenant, BackupSet $backupSet): void
     {
         if (! $tenant->isActive()) {

app/Services/Intune/SettingsCatalogDefinitionResolver.php

@@ -0,0 +1,272 @@
+<?php
+
+namespace App\Services\Intune;
+
+use App\Models\SettingsCatalogDefinition;
+use App\Services\Graph\GraphClientInterface;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+class SettingsCatalogDefinitionResolver
+{
+    private const CACHE_TTL = 60 * 60 * 24 * 30; // 30 days
+
+    private const MEMORY_CACHE_PREFIX = 'settings_catalog_def_';
+
+    public function __construct(
+        private GraphClientInterface $graphClient
+    ) {}
+
+    /**
+     * Resolve multiple definition IDs to their metadata.
+     *
+     * @param  array<string>  $definitionIds
+     * @return array<string, array> Map of definitionId => metadata
+     */
+    public function resolve(array $definitionIds): array
+    {
+        if (empty($definitionIds)) {
+            return [];
+        }
+
+        $definitions = [];
+        $missingIds = [];
+
+        // Step 1: Check memory cache
+        foreach ($definitionIds as $id) {
+            $cached = Cache::get(self::MEMORY_CACHE_PREFIX.$id);
+            if ($cached) {
+                $definitions[$id] = $cached;
+            } else {
+                $missingIds[] = $id;
+            }
+        }
+
+        if (empty($missingIds)) {
+            return $definitions;
+        }
+
+        // Step 2: Check database cache
+        $dbDefinitions = SettingsCatalogDefinition::findByDefinitionIds($missingIds);
+        foreach ($dbDefinitions as $definitionId => $dbDef) {
+            $metadata = $this->transformToMetadata($dbDef);
+            $definitions[$definitionId] = $metadata;
+
+            // Cache in memory
+            Cache::put(
+                self::MEMORY_CACHE_PREFIX.$definitionId,
+                $metadata,
+                now()->addSeconds(self::CACHE_TTL)
+            );
+
+            $missingIds = array_diff($missingIds, [$definitionId]);
+        }
+
+        if (empty($missingIds)) {
+            return $definitions;
+        }
+
+        // Step 3: Fetch from Graph API
+        try {
+            $graphDefinitions = $this->fetchFromGraph($missingIds);
+
+            foreach ($graphDefinitions as $definitionId => $metadata) {
+                // Store in database
+                $this->storeInDatabase($definitionId, $metadata);
+
+                // Cache in memory
+                Cache::put(
+                    self::MEMORY_CACHE_PREFIX.$definitionId,
+                    $metadata,
+                    now()->addSeconds(self::CACHE_TTL)
+                );
+
+                $definitions[$definitionId] = $metadata;
+            }
+        } catch (\Exception $e) {
+            Log::error('Failed to fetch setting definitions from Graph API', [
+                'definition_ids' => $missingIds,
+                'error' => $e->getMessage(),
+            ]);
+        }
+
+        // Step 4: Fallback for still missing definitions
+        foreach ($missingIds as $id) {
+            if (! isset($definitions[$id])) {
+                $fallback = $this->getFallbackMetadata($id);
+                $definitions[$id] = $fallback;
+
+                // Cache fallback in memory too (short TTL since it's not real data)
+                Cache::put(
+                    self::MEMORY_CACHE_PREFIX.$id,
+                    $fallback,
+                    now()->addMinutes(5) // Shorter TTL for fallbacks
+                );
+            }
+        }
+
+        return $definitions;
+    }
+
+    /**
+     * Resolve a single definition ID.
+     */
+    public function resolveOne(string $definitionId): ?array
+    {
+        $result = $this->resolve([$definitionId]);
+
+        return $result[$definitionId] ?? null;
+    }
+
+    /**
+     * Warm cache for definition IDs without returning data.
+     * Non-blocking: catches and logs errors.
+     */
+    public function warmCache(array $definitionIds): void
+    {
+        try {
+            $this->resolve($definitionIds);
+        } catch (\Exception $e) {
+            Log::warning('Failed to warm cache for setting definitions', [
+                'definition_ids' => $definitionIds,
+                'error' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    /**
+     * Clear cache for a specific definition or all definitions.
+     */
+    public function clearCache(?string $definitionId = null): void
+    {
+        if ($definitionId) {
+            Cache::forget(self::MEMORY_CACHE_PREFIX.$definitionId);
+            SettingsCatalogDefinition::where('definition_id', $definitionId)->delete();
+        } else {
+            // Clear all memory cache (prefix-based)
+            Cache::flush();
+            SettingsCatalogDefinition::truncate();
+        }
+    }
+
+    /**
+     * Fetch definitions from Graph API.
+     *
+     * @param  array<string>  $definitionIds
+     * @return array<string, array>
+     */
+    private function fetchFromGraph(array $definitionIds): array
+    {
+        $definitions = [];
+
+        // Note: Microsoft Graph API does not support "in" operator for $filter.
+        // We fetch each definition individually.
+        // Endpoint: /deviceManagement/configurationSettings/{definitionId}
+        foreach ($definitionIds as $definitionId) {
+            try {
+                $response = $this->graphClient->request(
+                    'GET',
+                    "/deviceManagement/configurationSettings/{$definitionId}"
+                );
+
+                if ($response->successful() && isset($response->data)) {
+                    $item = $response->data;
+                    $definitions[$definitionId] = [
+                        'displayName' => $item['displayName'] ?? $this->prettifyDefinitionId($definitionId),
+                        'description' => $item['description'] ?? null,
+                        'helpText' => $item['helpText'] ?? null,
+                        'categoryId' => $item['categoryId'] ?? null,
+                        'uxBehavior' => $item['uxBehavior'] ?? null,
+                        'raw' => $item,
+                    ];
+                }
+            } catch (\Exception $e) {
+                Log::warning('Failed to fetch definition from Graph API', [
+                    'definitionId' => $definitionId,
+                    'error' => $e->getMessage(),
+                ]);
+                // Continue with other definitions
+            }
+        }
+
+        return $definitions;
+    }
+
+    /**
+     * Store definition in database.
+     */
+    private function storeInDatabase(string $definitionId, array $metadata): void
+    {
+        SettingsCatalogDefinition::updateOrCreate(
+            ['definition_id' => $definitionId],
+            [
+                'display_name' => $metadata['displayName'],
+                'description' => $metadata['description'],
+                'help_text' => $metadata['helpText'],
+                'category_id' => $metadata['categoryId'],
+                'ux_behavior' => $metadata['uxBehavior'],
+                'raw' => $metadata['raw'],
+            ]
+        );
+    }
+
+    /**
+     * Transform database model to metadata array.
+     */
+    private function transformToMetadata(SettingsCatalogDefinition $definition): array
+    {
+        return [
+            'displayName' => $definition->display_name,
+            'description' => $definition->description,
+            'helpText' => $definition->help_text,
+            'categoryId' => $definition->category_id,
+            'uxBehavior' => $definition->ux_behavior,
+            'raw' => $definition->raw,
+        ];
+    }
+
+    /**
+     * Get fallback metadata for unknown definition.
+     */
+    private function getFallbackMetadata(string $definitionId): array
+    {
+        return [
+            'displayName' => $this->prettifyDefinitionId($definitionId),
+            'description' => null,
+            'helpText' => null,
+            'categoryId' => null,
+            'uxBehavior' => null,
+            'raw' => null,
+            'isFallback' => true,
+        ];
+    }
+
+    /**
+     * Prettify definition ID for fallback display.
+     * Example: "device_vendor_msft_policy_name" → "Device Vendor Msft Policy Name"
+     * Special handling for {tenantid} placeholders (Microsoft template definitions).
+     */
+    private function prettifyDefinitionId(string $definitionId): string
+    {
+        // Remove {tenantid} placeholder - it's a Microsoft template variable, not part of the name
+        $cleaned = str_replace(['{tenantid}', '_tenantid_', '_{tenantid}_'], ['', '_', '_'], $definitionId);
+
+        // Clean up consecutive underscores
+        $cleaned = preg_replace('/_+/', '_', $cleaned);
+        $cleaned = trim($cleaned, '_');
+
+        // Convert to title case
+        $prettified = Str::title(str_replace('_', ' ', $cleaned));
+
+        // Remove redundant prefixes to shorten labels
+        $prettified = preg_replace('/^Device Vendor Msft Passportforwork Policies\s+/', '', $prettified);
+        $prettified = preg_replace('/^Device Vendor Msft Passportforwork\s+/', 'Windows Hello - ', $prettified);
+
+        // Shorten common terms
+        $prettified = str_replace('Pincomplexity', 'PIN', $prettified);
+        $prettified = str_replace('Usepassportforwork', 'Enable Windows Hello', $prettified);
+
+        return $prettified;
+    }
+}

app/Services/Intune/VersionService.php

@@ -4,11 +4,15 @@
 
 use App\Models\Policy;
 use App\Models\PolicyVersion;
+use App\Models\Tenant;
 use Carbon\CarbonImmutable;
 
 class VersionService
 {
-    public function __construct(private readonly AuditLogger $auditLogger) {}
+    public function __construct(
+        private readonly AuditLogger $auditLogger,
+        private readonly PolicySnapshotService $snapshotService,
+    ) {}
 
     public function captureVersion(
         Policy $policy,
@@ -47,6 +51,30 @@ public function captureVersion(
         return $version;
     }
 
+    public function captureFromGraph(
+        Tenant $tenant,
+        Policy $policy,
+        ?string $createdBy = null,
+        array $metadata = [],
+    ): PolicyVersion {
+        $snapshot = $this->snapshotService->fetch($tenant, $policy, $createdBy);
+
+        if (isset($snapshot['failure'])) {
+            $reason = $snapshot['failure']['reason'] ?? 'Unable to fetch policy snapshot';
+
+            throw new \RuntimeException($reason);
+        }
+
+        $metadata = array_merge(['source' => 'version_capture'], $metadata);
+
+        return $this->captureVersion(
+            policy: $policy,
+            payload: $snapshot['payload'],
+            createdBy: $createdBy,
+            metadata: $metadata,
+        );
+    }
+
     private function nextVersionNumber(Policy $policy): int
     {
         $current = PolicyVersion::query()

app/Support/Concerns/InteractsWithODataTypes.php

@@ -17,6 +17,10 @@ protected static function odataTypeMap(): array
                 'macOS' => '#microsoft.graph.macOSGeneralDeviceConfiguration',
                 'all' => '#microsoft.graph.deviceConfiguration',
             ],
+            'settingsCatalogPolicy' => [
+                'windows' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+                'all' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+            ],
             'deviceCompliancePolicy' => [
                 'windows' => '#microsoft.graph.windows10CompliancePolicy',
                 'ios' => '#microsoft.graph.iosCompliancePolicy',
@@ -75,8 +79,18 @@ public static function expectedODataType(?string $policyType, ?string $platform
      */
     public static function validateODataType(array $snapshot, ?string $policyType = null, ?string $platform = null): array
     {
-        $expected = static::expectedODataType($policyType, $platform);
         $actual = $snapshot['@odata.type'] ?? null;
+        $contractFamily = config("graph_contracts.types.$policyType.type_family", []);
+
+        if ($actual && $policyType && in_array(strtolower($actual), array_map('strtolower', $contractFamily), true)) {
+            return [
+                'matches' => true,
+                'expected' => $actual,
+                'actual' => $actual,
+            ];
+        }
+
+        $expected = static::expectedODataType($policyType, $platform);
 
         if ($expected === null || $actual === null) {
             return [

composer.json

@@ -9,7 +9,8 @@
         "php": "^8.2",
         "filament/filament": "^4.0",
         "laravel/framework": "^12.0",
-        "laravel/tinker": "^2.10.1"
+        "laravel/tinker": "^2.10.1",
+        "pepperfm/filament-json": "^4"
     },
     "require-dev": {
         "barryvdh/laravel-debugbar": "^3.16",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "4ee38f2ac2d8cdc0f333cc36bbeb7eaa",
+    "content-hash": "c4f08fd9fc4b86cc13b75332dd6e1b7a",
     "packages": [
         {
             "name": "anourvalar/eloquent-serialize",
@@ -4109,6 +4109,162 @@
             },
             "time": "2025-09-24T15:06:41+00:00"
         },
+        {
+            "name": "pepperfm/filament-json",
+            "version": "4.0.11",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/pepperfm/filament-json.git",
+                "reference": "9248012572fc6cf8c0ffe5caad7ba6567708079a"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/pepperfm/filament-json/zipball/9248012572fc6cf8c0ffe5caad7ba6567708079a",
+                "reference": "9248012572fc6cf8c0ffe5caad7ba6567708079a",
+                "shasum": ""
+            },
+            "require": {
+                "filament/filament": "^4.0",
+                "pepperfm/ssd-for-laravel": "^0.0.8",
+                "php": "^8.2",
+                "spatie/laravel-package-tools": "^1.15.0"
+            },
+            "require-dev": {
+                "friendsofphp/php-cs-fixer": "^3.59",
+                "larastan/larastan": "^3.0",
+                "laravel/pint": "^1.0",
+                "nunomaduro/collision": "^8.0",
+                "orchestra/testbench": "^10.4",
+                "pestphp/pest": "^3.0",
+                "pestphp/pest-plugin-arch": "^3.0",
+                "pestphp/pest-plugin-laravel": "^3.0",
+                "pestphp/pest-plugin-livewire": "^3.0",
+                "phpstan/extension-installer": "^1.1",
+                "phpstan/phpstan": "^2.1",
+                "phpstan/phpstan-deprecation-rules": "^2.0",
+                "phpstan/phpstan-phpunit": "^2.0",
+                "spatie/laravel-ray": "^1.26"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "FilamentJson": "PepperFM\\FilamentJson\\Facades\\FilamentJson"
+                    },
+                    "providers": [
+                        "PepperFM\\FilamentJson\\FilamentJsonServiceProvider"
+                    ]
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "PepperFM\\FilamentJson\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "PepperFM",
+                    "email": "Damon3453@yandex.ru",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Filament plugin for processing JSON field",
+            "homepage": "https://github.com/pepperfm/filament-json",
+            "keywords": [
+                "filament-json",
+                "laravel",
+                "pepperfm"
+            ],
+            "support": {
+                "issues": "https://github.com/pepperfm/filament-json/issues",
+                "source": "https://github.com/pepperfm/filament-json"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/pepperfm",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-08-17T23:03:32+00:00"
+        },
+        {
+            "name": "pepperfm/ssd-for-laravel",
+            "version": "0.0.8",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/pepperfm/ssd-for-laravel.git",
+                "reference": "342a3567356b8a587d117ed5fc7166e95f1209ec"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/pepperfm/ssd-for-laravel/zipball/342a3567356b8a587d117ed5fc7166e95f1209ec",
+                "reference": "342a3567356b8a587d117ed5fc7166e95f1209ec",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/http": ">=10.0",
+                "illuminate/support": ">=10.0",
+                "php": "^8.2"
+            },
+            "conflict": {
+                "laravel/framework": "<10.20.0"
+            },
+            "require-dev": {
+                "friendsofphp/php-cs-fixer": "^3.59",
+                "laravel/pint": "^1.16",
+                "orchestra/testbench": "^v8.14|^9.11",
+                "pestphp/pest": "^3.0",
+                "pestphp/pest-plugin-laravel": "^3.0",
+                "phpunit/phpunit": "^10.0|^11.0",
+                "spatie/laravel-ray": "^1.37"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "SsdForLaravel": "Pepperfm\\Ssd\\Facades\\SsdFacade"
+                    },
+                    "providers": [
+                        "Pepperfm\\Ssd\\Providers\\SsdServiceProvider"
+                    ]
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Pepperfm\\Ssd\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Dmitry Gaponenko",
+                    "email": "Damon3453@yandex.ru",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Simple Slim DTO",
+            "homepage": "https://github.com/pepperfm/ssd-for-laravel",
+            "keywords": [
+                "Simple",
+                "dto",
+                "pepperfm",
+                "schema",
+                "ssd-for-laravel",
+                "typehint"
+            ],
+            "support": {
+                "issues": "https://github.com/pepperfm/ssd-for-laravel/issues",
+                "source": "https://github.com/pepperfm/ssd-for-laravel/tree/0.0.8"
+            },
+            "time": "2025-02-26T00:08:40+00:00"
+        },
         {
             "name": "phpoption/phpoption",
             "version": "1.9.4",

config/graph_contracts.php

@@ -0,0 +1,185 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Graph Contract Registry
+    |--------------------------------------------------------------------------
+    |
+    | Central place to describe Graph endpoints, allowed selects/expands, and
+    | type families for supported policy types. Used for capability fallbacks
+    | and drift checks.
+    |
+    */
+    'types' => [
+        'deviceConfiguration' => [
+            'resource' => 'deviceManagement/deviceConfigurations',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'version', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.deviceConfiguration',
+                '#microsoft.graph.windows10CustomConfiguration',
+                '#microsoft.graph.iosGeneralDeviceConfiguration',
+                '#microsoft.graph.androidGeneralDeviceConfiguration',
+                '#microsoft.graph.macOSGeneralDeviceConfiguration',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'settingsCatalogPolicy' => [
+            'resource' => 'deviceManagement/configurationPolicies',
+            'allowed_select' => ['id', 'name', 'displayName', 'description', '@odata.type', 'version', 'platforms', 'technologies', 'roleScopeTagIds', 'lastModifiedDateTime'],
+            'allowed_expand' => ['settings'],
+            'type_family' => [
+                '#microsoft.graph.deviceManagementConfigurationPolicy',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+            'update_whitelist' => [
+                'name',
+                'description',
+            ],
+            'update_map' => [
+                'displayName' => 'name',
+            ],
+            'update_strip_keys' => [
+                'platforms',
+                'technologies',
+                'templateReference',
+                'assignments',
+            ],
+            'member_hydration_strategy' => 'subresource_settings',
+            'subresources' => [
+                'settings' => [
+                    'path' => 'deviceManagement/configurationPolicies/{id}/settings',
+                    'collection' => true,
+                    'paging' => true,
+                    'allowed_select' => [],
+                    'allowed_expand' => [],
+                ],
+            ],
+            'settings_write' => [
+                'path_template' => 'deviceManagement/configurationPolicies/{id}/settings/{settingId}',
+                'method' => 'PATCH',
+            ],
+            'update_strategy' => 'settings_catalog_policy_with_settings',
+        ],
+        'deviceCompliancePolicy' => [
+            'resource' => 'deviceManagement/deviceCompliancePolicies',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'version', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.deviceCompliancePolicy',
+                '#microsoft.graph.windows10CompliancePolicy',
+                '#microsoft.graph.iosCompliancePolicy',
+                '#microsoft.graph.androidCompliancePolicy',
+                '#microsoft.graph.macOSCompliancePolicy',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'appProtectionPolicy' => [
+            'resource' => 'deviceAppManagement/managedAppPolicies',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'version'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.targetedManagedAppProtection',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'conditionalAccessPolicy' => [
+            'resource' => 'identity/conditionalAccess/policies',
+            'allowed_select' => ['id', 'displayName', 'state', 'createdDateTime', 'modifiedDateTime', '@odata.type'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.conditionalAccessPolicy',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'deviceManagementScript' => [
+            'resource' => 'deviceManagement/deviceManagementScripts',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.deviceManagementScript',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'enrollmentRestriction' => [
+            'resource' => 'deviceManagement/deviceEnrollmentConfigurations',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'version'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.deviceEnrollmentConfiguration',
+                '#microsoft.graph.windows10EnrollmentCompletionPageConfiguration',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'windowsAutopilotDeploymentProfile' => [
+            'resource' => 'deviceManagement/windowsAutopilotDeploymentProfiles',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.windowsAutopilotDeploymentProfile',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'windowsEnrollmentStatusPage' => [
+            'resource' => 'deviceManagement/deviceEnrollmentConfigurations',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'version'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.windows10EnrollmentCompletionPageConfiguration',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'endpointSecurityIntent' => [
+            'resource' => 'deviceManagement/intents',
+            'allowed_select' => ['id', 'displayName', 'description', '@odata.type', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.deviceManagementIntent',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+        'mobileApp' => [
+            'resource' => 'deviceAppManagement/mobileApps',
+            'allowed_select' => ['id', 'displayName', 'publisher', 'description', '@odata.type', 'createdDateTime', 'lastModifiedDateTime'],
+            'allowed_expand' => [],
+            'type_family' => [
+                '#microsoft.graph.mobileApp',
+            ],
+            'create_method' => 'POST',
+            'update_method' => 'PATCH',
+            'id_field' => 'id',
+            'hydration' => 'properties',
+        ],
+    ],
+];

config/intune_permissions.php

@@ -56,6 +56,12 @@
             'description' => 'Read directory data needed for tenant health checks.',
             'features' => ['tenant-health'],
         ],
+        [
+            'key' => 'DeviceManagementScripts.ReadWrite.All',
+            'type' => 'application',
+            'description' => 'Read directory data needed for tenant health checks.',
+            'features' => ['script-management'],
+        ],
     ],
     // Stub list of permissions already granted to the service principal (used for display in Tenant verification UI).
     // Diese Liste sollte mit den tatsächlich in Entra ID granted permissions übereinstimmen.
@@ -69,6 +75,7 @@
         'DeviceManagementServiceConfig.Read.All',
         'Directory.Read.All',
         'User.Read',
+        'DeviceManagementScripts.ReadWrite.All',
 
         // Required permissions (müssen in Entra ID granted werden):
         // Wenn diese fehlen, erscheinen sie als "missing" in der UI

config/tenantpilot.php

@@ -12,6 +12,16 @@
             'restore' => 'enabled',
             'risk' => 'medium',
         ],
+        [
+            'type' => 'settingsCatalogPolicy',
+            'label' => 'Settings Catalog Policy',
+            'category' => 'Configuration',
+            'platform' => 'windows',
+            'endpoint' => 'deviceManagement/configurationPolicies',
+            'backup' => 'full',
+            'restore' => 'enabled',
+            'risk' => 'medium',
+        ],
         [
             'type' => 'deviceCompliancePolicy',
             'label' => 'Device Compliance',

database/migrations/2025_12_13_212126_create_settings_catalog_definitions_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('settings_catalog_definitions', function (Blueprint $table) {
+            $table->id();
+            $table->string('definition_id', 500)->unique();
+            $table->string('display_name');
+            $table->text('description')->nullable();
+            $table->text('help_text')->nullable();
+            $table->string('category_id')->nullable();
+            $table->string('ux_behavior', 100)->nullable();
+            $table->jsonb('raw');
+            $table->timestamps();
+
+            // Indexes
+            $table->index('definition_id');
+            $table->index('category_id');
+            // GIN index for JSONB (PostgreSQL)
+            $table->rawIndex('raw', 'idx_settings_catalog_definitions_raw_gin', 'gin');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('settings_catalog_definitions');
+    }
+};

resources/views/filament/infolists/entries/normalized-settings.blade.php

@@ -2,10 +2,13 @@
     $normalized = $getState() ?? [];
     $warnings = $normalized['warnings'] ?? [];
     $settings = $normalized['settings'] ?? [];
+    $settingsTable = $normalized['settings_table'] ?? null;
+    $settingsTableRows = is_array($settingsTable) ? ($settingsTable['rows'] ?? []) : [];
+    $context = $normalized['context'] ?? 'policy';
+    $recordId = $normalized['record_id'] ?? null;
 @endphp
 
 <div class="space-y-3">
-    <div class="text-sm font-semibold text-gray-800">Normalized settings</div>
     @if (! empty($warnings))
         <div class="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-800">
             <div class="font-semibold">Warnings</div>
@@ -17,35 +20,85 @@
         </div>
     @endif
 
-    @if (empty($settings))
+    @if (empty($settings) && empty($settingsTableRows))
         <p class="text-sm text-gray-600">No settings available.</p>
     @endif
 
+    @if (! empty($settingsTableRows))
+        <div class="space-y-2 rounded-md border border-gray-200 bg-white p-3 shadow-sm">
+            <div class="text-sm font-semibold text-gray-800">{{ is_array($settingsTable) ? ($settingsTable['title'] ?? 'Settings') : 'Settings' }}</div>
+            <livewire:settings-catalog-settings-table
+                :settings-rows="$settingsTableRows"
+                :context="$context"
+                :key="$recordId ? ('sc-settings-'.$context.'-'.$recordId) : ('sc-settings-'.$context)"
+            />
+        </div>
+    @endif
+
     @foreach ($settings as $block)
         <div class="space-y-2 rounded-md border border-gray-200 bg-white p-3 shadow-sm">
             <div class="text-sm font-semibold text-gray-800">{{ $block['title'] ?? 'Settings' }}</div>
 
             @if (($block['type'] ?? 'keyValue') === 'table')
-                <div class="overflow-x-auto">
+                @php
-                    <table class="w-full text-left text-sm">
+                    $columns = $block['columns'] ?? null;
+                    $hasColumns = is_array($columns) && ! empty($columns);
+                    $columnMeta = [
+                        'definitionId' => ['width' => 'w-[35%]', 'style' => 'width: 35%;', 'cell' => 'font-mono text-xs break-all whitespace-normal', 'cellStyle' => 'word-break: break-all; overflow-wrap: anywhere; white-space: normal;'],
+                        'instanceType' => ['width' => 'w-[20%]', 'style' => 'width: 20%;', 'cell' => 'font-mono text-xs break-all whitespace-normal', 'cellStyle' => 'word-break: break-all; overflow-wrap: anywhere; white-space: normal;'],
+                        'value' => ['width' => 'w-[25%]', 'style' => 'width: 25%;', 'cell' => 'break-words whitespace-pre-wrap', 'cellStyle' => 'overflow-wrap: anywhere; white-space: pre-wrap;'],
+                        'path' => ['width' => 'w-[20%]', 'style' => 'width: 20%;', 'cell' => 'font-mono text-xs break-all whitespace-normal', 'cellStyle' => 'word-break: break-all; overflow-wrap: anywhere; white-space: normal;'],
+                    ];
+                @endphp
+                <div class="overflow-x-auto rounded-lg border border-gray-200" style="overflow-x: auto;">
+                    <table class="min-w-[900px] w-full table-fixed text-left text-sm" style="table-layout: fixed; width: 100%; min-width: 900px;">
                         <thead class="bg-gray-50 text-gray-700">
                             <tr>
-                                <th class="px-3 py-2">Path</th>
+                                @if ($hasColumns)
-                                <th class="px-3 py-2">Value</th>
+                                    @foreach ($columns as $column)
+                                        @php
+                                            $key = $column['key'] ?? null;
+                                            $meta = is_string($key) ? ($columnMeta[$key] ?? []) : [];
+                                        @endphp
+                                        <th class="px-3 py-2 {{ $meta['width'] ?? '' }}" style="{{ $meta['style'] ?? '' }}">{{ $column['label'] ?? $column['key'] ?? '-' }}</th>
+                                    @endforeach
+                                @else
+                                    <th class="px-3 py-2">Path</th>
+                                    <th class="px-3 py-2">Value</th>
+                                @endif
                             </tr>
                         </thead>
                         <tbody class="divide-y divide-gray-100">
                             @foreach ($block['rows'] ?? [] as $row)
                                 <tr>
-                                    <td class="px-3 py-2 align-top">
+                                    @if ($hasColumns)
-                                        <div class="font-medium text-gray-800">{{ $row['path'] ?? '-' }}</div>
+                                        @foreach ($columns as $column)
-                                        @if (! empty($row['label']))
+                                            @php
-                                            <div class="text-xs text-gray-600">{{ $row['label'] }}</div>
+                                                $key = $column['key'] ?? null;
-                                        @endif
+                                                $cell = is_string($key) ? ($row[$key] ?? null) : null;
-                                    </td>
+                                                $meta = is_string($key) ? ($columnMeta[$key] ?? []) : [];
-                                    <td class="px-3 py-2 align-top text-gray-800">
+                                            @endphp
-                                        {{ is_array($row['value'] ?? null) ? json_encode($row['value'], JSON_PRETTY_PRINT) : ($row['value'] ?? '-') }}
+                                            <td class="px-3 py-2 align-top text-gray-800 {{ $meta['cell'] ?? 'whitespace-pre-wrap' }}" style="{{ $meta['cellStyle'] ?? '' }}">
-                                    </td>
+                                                @if (is_array($cell))
+                                                    <pre class="overflow-x-auto text-xs">{{ json_encode($cell, JSON_PRETTY_PRINT) }}</pre>
+                                                @elseif (is_bool($cell))
+                                                    <span>{{ $cell ? 'true' : 'false' }}</span>
+                                                @else
+                                                    <span title="{{ is_string($cell) ? $cell : '' }}">{{ $cell ?? '-' }}</span>
+                                                @endif
+                                            </td>
+                                        @endforeach
+                                    @else
+                                        <td class="px-3 py-2 align-top">
+                                            <div class="font-mono text-xs font-medium text-gray-800 break-all whitespace-normal" style="word-break: break-all; overflow-wrap: anywhere; white-space: normal;">{{ $row['path'] ?? '-' }}</div>
+                                            @if (! empty($row['label']))
+                                                <div class="text-xs text-gray-600">{{ $row['label'] }}</div>
+                                            @endif
+                                        </td>
+                                        <td class="px-3 py-2 align-top text-gray-800 break-words whitespace-pre-wrap" style="overflow-wrap: anywhere; white-space: pre-wrap;">
+                                            {{ is_array($row['value'] ?? null) ? json_encode($row['value'], JSON_PRETTY_PRINT) : ($row['value'] ?? '-') }}
+                                        </td>
+                                    @endif
                                 </tr>
                             @endforeach
                         </tbody>

resources/views/filament/infolists/entries/policy-settings-standard.blade.php

@@ -0,0 +1,151 @@
+@php
+    use Illuminate\Support\Str;
+
+    // Extract state from Filament ViewEntry
+    $state = $getState();
+    $status = $state['status'] ?? 'success';
+    $warnings = $state['warnings'] ?? [];
+    $settings = $state['settings'] ?? [];
+    $settingsTable = $state['settings_table'] ?? null;
+@endphp
+
+<div class="space-y-4">
+    {{-- Warnings --}}
+    @if(!empty($warnings))
+        <x-filament::section>
+            <div class="space-y-2">
+                @foreach($warnings as $warning)
+                    <div class="flex items-start gap-2 text-sm text-warning-600 dark:text-warning-400">
+                        <svg class="w-5 h-5 flex-shrink-0 mt-0.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
+                        </svg>
+                        <span>{{ $warning }}</span>
+                    </div>
+                @endforeach
+            </div>
+        </x-filament::section>
+    @endif
+
+    {{-- Settings Table (for Settings Catalog legacy format) --}}
+    @if($settingsTable && !empty($settingsTable['rows']))
+        <x-filament::section
+            :heading="$settingsTable['title'] ?? 'Settings'"
+            :description="$settingsTable['description'] ?? null"
+        >
+            <x-slot name="headerEnd">
+                <span class="text-sm text-gray-500 dark:text-gray-400">
+                    {{ count($settingsTable['rows']) }} {{ Str::plural('setting', count($settingsTable['rows'])) }}
+                </span>
+            </x-slot>
+
+            <div class="divide-y divide-gray-200 dark:divide-gray-700">
+                @foreach($settingsTable['rows'] as $row)
+                    <div class="py-3 sm:grid sm:grid-cols-3 sm:gap-4">
+                        <dt class="text-sm font-medium text-gray-500 dark:text-gray-400">
+                            {{ $row['definition'] ?? $row['label'] ?? $row['path'] ?? 'Setting' }}
+                        </dt>
+                        <dd class="mt-1 sm:mt-0 sm:col-span-2">
+                            <span class="text-sm text-gray-900 dark:text-white">
+                                @if(is_bool($row['value']))
+                                    <x-filament::badge :color="$row['value'] ? 'success' : 'gray'" size="sm">
+                                        {{ $row['value'] ? 'Enabled' : 'Disabled' }}
+                                    </x-filament::badge>
+                                @elseif(is_numeric($row['value']))
+                                    <span class="font-mono font-semibold">{{ $row['value'] }}</span>
+                                @else
+                                    {{ $row['value'] ?? 'N/A' }}
+                                @endif
+                            </span>
+                        </dd>
+                    </div>
+                @endforeach
+            </div>
+        </x-filament::section>
+    @endif
+
+    {{-- Settings Blocks (for OMA Settings, Key/Value pairs, etc.) --}}
+    @foreach($settings as $block)
+        @if($block['type'] === 'table')
+            <x-filament::section
+                :heading="$block['title'] ?? 'Settings'"
+                collapsible
+            >
+                <x-slot name="headerEnd">
+                    <span class="text-sm text-gray-500 dark:text-gray-400">
+                        {{ count($block['rows'] ?? []) }} {{ Str::plural('item', count($block['rows'] ?? [])) }}
+                    </span>
+                </x-slot>
+
+                <div class="divide-y divide-gray-200 dark:divide-gray-700">
+                    @foreach($block['rows'] ?? [] as $row)
+                        <div class="py-3 sm:grid sm:grid-cols-3 sm:gap-4">
+                            <dt class="text-sm font-medium text-gray-500 dark:text-gray-400">
+                                {{ $row['label'] ?? $row['path'] ?? 'Setting' }}
+                                @if(!empty($row['description']))
+                                    <p class="text-xs text-gray-400 mt-0.5">{{ Str::limit($row['description'], 80) }}</p>
+                                @endif
+                            </dt>
+                            <dd class="mt-1 sm:mt-0 sm:col-span-2">
+                                @if(is_bool($row['value']))
+                                    <x-filament::badge :color="$row['value'] ? 'success' : 'gray'" size="sm">
+                                        {{ $row['value'] ? 'Enabled' : 'Disabled' }}
+                                    </x-filament::badge>
+                                @elseif(is_numeric($row['value']))
+                                    <span class="font-mono text-sm font-semibold text-gray-900 dark:text-white">
+                                        {{ $row['value'] }}
+                                    </span>
+                                @else
+                                    <span class="text-sm text-gray-900 dark:text-white break-words">
+                                        {{ Str::limit($row['value'] ?? 'N/A', 200) }}
+                                    </span>
+                                @endif
+                            </dd>
+                        </div>
+                    @endforeach
+                </div>
+            </x-filament::section>
+
+        @elseif($block['type'] === 'keyValue')
+            <x-filament::section
+                :heading="$block['title'] ?? 'Settings'"
+                collapsible
+            >
+                <x-slot name="headerEnd">
+                    <span class="text-sm text-gray-500 dark:text-gray-400">
+                        {{ count($block['entries'] ?? []) }} {{ Str::plural('entry', count($block['entries'] ?? [])) }}
+                    </span>
+                </x-slot>
+
+                <div class="divide-y divide-gray-200 dark:divide-gray-700">
+                    @foreach($block['entries'] ?? [] as $entry)
+                        <div class="py-3 sm:grid sm:grid-cols-3 sm:gap-4">
+                            <dt class="text-sm font-medium text-gray-500 dark:text-gray-400">
+                                {{ $entry['key'] }}
+                            </dt>
+                            <dd class="mt-1 sm:mt-0 sm:col-span-2">
+                                <span class="text-sm text-gray-900 dark:text-white break-words">
+                                    {{ Str::limit($entry['value'] ?? 'N/A', 200) }}
+                                </span>
+                            </dd>
+                        </div>
+                    @endforeach
+                </div>
+            </x-filament::section>
+        @endif
+    @endforeach
+
+    {{-- Empty state --}}
+    @if(empty($settings) && (!$settingsTable || empty($settingsTable['rows'])))
+        <div class="text-center py-12">
+            <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>
+            </svg>
+            <p class="mt-4 text-sm text-gray-500 dark:text-gray-400">
+                No settings data available
+            </p>
+            <p class="mt-1 text-xs text-gray-400 dark:text-gray-500">
+                This policy may not contain settings, or they are in an unsupported format
+            </p>
+        </div>
+    @endif
+</div>

resources/views/filament/infolists/entries/restore-results.blade.php

@@ -0,0 +1,153 @@
+@php
+    $results = $getState() ?? [];
+@endphp
+
+@if (empty($results))
+    <p class="text-sm text-gray-600">No results recorded.</p>
+@else
+    @php
+        $needsAttention = collect($results)->contains(function ($item) {
+            $status = $item['status'] ?? null;
+
+            return in_array($status, ['partial', 'manual_required'], true);
+        });
+    @endphp
+
+    <div class="space-y-3">
+        @if ($needsAttention)
+            <div class="rounded border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-900">
+                Some settings could not be applied automatically. Review the per-setting details below.
+            </div>
+        @endif
+        @foreach ($results as $item)
+            <div class="rounded border border-gray-200 bg-white p-3 shadow-sm">
+                <div class="flex items-center justify-between text-sm">
+                    <div class="font-semibold text-gray-900">
+                        {{ $item['policy_identifier'] ?? $item['policy_id'] ?? 'Policy' }}
+                        <span class="ml-2 text-xs text-gray-500">{{ $item['policy_type'] ?? '' }}</span>
+                    </div>
+                    @php
+                        $status = $item['status'] ?? 'unknown';
+                        $statusColor = match ($status) {
+                            'applied' => 'text-green-700 bg-green-100 border-green-200',
+                            'dry_run' => 'text-blue-700 bg-blue-100 border-blue-200',
+                            'partial' => 'text-amber-900 bg-amber-50 border-amber-200',
+                            'manual_required' => 'text-amber-900 bg-amber-100 border-amber-200',
+                            'failed' => 'text-red-700 bg-red-100 border-red-200',
+                            default => 'text-gray-700 bg-gray-100 border-gray-200',
+                        };
+                    @endphp
+                    <span class="rounded border px-2 py-0.5 text-xs font-semibold uppercase tracking-wide {{ $statusColor }}">
+                        {{ $status }}
+                    </span>
+                </div>
+
+                @if (! empty($item['reason']))
+                    <div class="mt-2 text-sm text-gray-800">
+                        {{ $item['reason'] }}
+                    </div>
+                @endif
+
+                @if (! empty($item['graph_error_message']) || ! empty($item['graph_error_code']))
+                    <div class="mt-2 rounded border border-amber-200 bg-amber-50 px-2 py-1 text-xs text-amber-900">
+                        <div class="font-semibold">Graph error</div>
+                        <div>{{ $item['graph_error_message'] ?? 'Unknown error' }}</div>
+                        @if (! empty($item['graph_error_code']))
+                            <div class="mt-1 text-[11px] text-amber-800">Code: {{ $item['graph_error_code'] }}</div>
+                        @endif
+                        @if (! empty($item['graph_request_id']) || ! empty($item['graph_client_request_id']))
+                            <details class="mt-1">
+                                <summary class="cursor-pointer text-[11px] font-semibold text-amber-800">Details</summary>
+                                <div class="mt-1 space-y-0.5 text-[11px] text-amber-800">
+                                    @if (! empty($item['graph_request_id']))
+                                        <div>request-id: {{ $item['graph_request_id'] }}</div>
+                                    @endif
+                                    @if (! empty($item['graph_client_request_id']))
+                                        <div>client-request-id: {{ $item['graph_client_request_id'] }}</div>
+                                    @endif
+                                </div>
+                            </details>
+                        @endif
+                    </div>
+                @endif
+
+                @if (! empty($item['settings_apply']) && is_array($item['settings_apply']))
+                    @php
+                        $apply = $item['settings_apply'];
+                        $total = (int) ($apply['total'] ?? 0);
+                        $applied = (int) ($apply['applied'] ?? 0);
+                        $failed = (int) ($apply['failed'] ?? 0);
+                        $manual = (int) ($apply['manual_required'] ?? 0);
+                        $issues = $apply['issues'] ?? [];
+                    @endphp
+
+                    <div class="mt-2 text-xs text-gray-700">
+                        Settings applied: {{ $applied }}/{{ $total }}
+                        @if ($failed > 0 || $manual > 0)
+                            • {{ $failed }} failed • {{ $manual }} manual
+                        @endif
+                    </div>
+
+                    @if (! empty($issues))
+                        <details class="mt-2 rounded border border-amber-200 bg-amber-50 px-2 py-1 text-xs text-amber-900">
+                            <summary class="cursor-pointer font-semibold">Settings requiring attention</summary>
+                            <div class="mt-2 space-y-2">
+                                @foreach ($issues as $issue)
+                                    @php
+                                        $issueStatus = $issue['status'] ?? 'unknown';
+                                        $issueColor = match ($issueStatus) {
+                                            'failed' => 'text-red-700 bg-red-100 border-red-200',
+                                            'manual_required' => 'text-amber-900 bg-amber-100 border-amber-200',
+                                            default => 'text-gray-700 bg-gray-100 border-gray-200',
+                                        };
+                                    @endphp
+                                    <div class="rounded border border-amber-200 bg-white p-2">
+                                        <div class="flex items-center justify-between">
+                                            <div class="font-semibold text-gray-900">
+                                                Setting {{ $issue['setting_id'] ?? 'unknown' }}
+                                            </div>
+                                            <span class="rounded border px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide {{ $issueColor }}">
+                                                {{ $issueStatus }}
+                                            </span>
+                                        </div>
+
+                                        @if (! empty($issue['reason']))
+                                            <div class="mt-1 text-[11px] text-gray-800">
+                                                {{ $issue['reason'] }}
+                                            </div>
+                                        @endif
+
+                                        @if (! empty($issue['graph_error_message']) || ! empty($issue['graph_error_code']))
+                                            <div class="mt-1 text-[11px] text-amber-900">
+                                                <div>{{ $issue['graph_error_message'] ?? 'Unknown error' }}</div>
+                                                @if (! empty($issue['graph_error_code']))
+                                                    <div class="mt-0.5 text-amber-800">Code: {{ $issue['graph_error_code'] }}</div>
+                                                @endif
+                                                @if (! empty($issue['graph_request_id']) || ! empty($issue['graph_client_request_id']))
+                                                    <div class="mt-0.5 space-y-0.5 text-amber-800">
+                                                        @if (! empty($issue['graph_request_id']))
+                                                            <div>request-id: {{ $issue['graph_request_id'] }}</div>
+                                                        @endif
+                                                        @if (! empty($issue['graph_client_request_id']))
+                                                            <div>client-request-id: {{ $issue['graph_client_request_id'] }}</div>
+                                                        @endif
+                                                    </div>
+                                                @endif
+                                            </div>
+                                        @endif
+                                    </div>
+                                @endforeach
+                            </div>
+                        </details>
+                    @endif
+                @endif
+
+                @if (! empty($item['platform']))
+                    <div class="mt-2 text-[11px] text-gray-500">
+                        Platform: {{ $item['platform'] }}
+                    </div>
+                @endif
+            </div>
+        @endforeach
+    </div>
+@endif

resources/views/filament/infolists/entries/settings-catalog-grouped.blade.php

@@ -0,0 +1,147 @@
+@php
+    use Illuminate\Support\Str;
+
+    // Extract groups from Filament ViewEntry state using $getState()
+    $groups = [];
+    $searchQuery = $searchQuery ?? '';
+
+    // Use $getState() function provided by Filament Entry component
+    $state = $getState();
+    
+    // Handle different types: object, array, string, closure
+    if ($state instanceof \Closure) {
+        $state = $state(); // Execute closure to get actual data
+    }
+    
+    if (is_object($state)) {
+        // Convert stdClass or other objects to array
+        $state = json_decode(json_encode($state), true);
+    }
+    
+    if (is_string($state) && Str::startsWith(trim($state), '{')) {
+        $state = json_decode($state, true);
+    }
+    
+    if (is_array($state)) {
+        $groups = $state['groups'] ?? $state;
+    }
+
+    // Ensure groups is always an array
+    $groups = is_array($groups) ? $groups : [];
+@endphp
+
+<div class="space-y-4">
+    @if(empty($groups))
+        <div class="text-center py-8">
+            <p class="text-gray-500 dark:text-gray-400">No settings available</p>
+        </div>
+    @else
+        @foreach($groups as $groupIndex => $group)
+            @php
+                // Filter settings by search query
+                $filteredSettings = collect($group['settings'] ?? [])->filter(function($setting) use ($searchQuery) {
+                    if (empty($searchQuery)) {
+                        return true;
+                    }
+                    
+                    $searchLower = strtolower($searchQuery);
+                    return str_contains(strtolower($setting['label'] ?? ''), $searchLower) ||
+                           str_contains(strtolower($setting['value_display'] ?? ''), $searchLower);
+                })->all();
+                
+                $settingCount = count($filteredSettings);
+            @endphp
+
+            @if($settingCount > 0)
+                <x-filament::section
+                    :heading="$group['title'] ?? 'Settings'"
+                    :description="$group['description'] ?? null"
+                    collapsible
+                    :collapsed="$groupIndex > 0"
+                >
+                    <x-slot name="headerEnd">
+                        <span class="text-sm text-gray-500 dark:text-gray-400">
+                            {{ $settingCount }} {{ Str::plural('setting', $settingCount) }}
+                        </span>
+                    </x-slot>
+
+                    <dl class="divide-y divide-gray-200 dark:divide-gray-700">
+                        @foreach($filteredSettings as $setting)
+                            <div class="py-3 grid grid-cols-1 md:grid-cols-3 md:gap-4 items-start">
+                                <dt class="text-sm font-medium text-gray-500 dark:text-gray-400 break-words">
+                                    {{ $setting['label'] }}
+                                </dt>
+                                <dd class="mt-1 md:mt-0 md:col-span-2 break-words">
+                                    <div class="flex flex-wrap items-center gap-3">
+                                        @if(is_bool($setting['value_raw']))
+                                            <x-filament::badge :color="$setting['value_raw'] ? 'success' : 'gray'" size="sm">
+                                                {{ $setting['value_display'] }}
+                                            </x-filament::badge>
+                                        @elseif(is_int($setting['value_raw']))
+                                            <span class="font-mono text-sm font-semibold text-gray-900 dark:text-white">
+                                                {{ $setting['value_display'] }}
+                                            </span>
+                                        @elseif(str_contains(strtolower($setting['value_display']), 'enabled') || str_contains(strtolower($setting['value_display']), 'disabled'))
+                                            <x-filament::badge :color="str_contains(strtolower($setting['value_display']), 'enabled') ? 'success' : 'gray'" size="sm">
+                                                {{ $setting['value_display'] }}
+                                            </x-filament::badge>
+                                        @else
+                                            <span class="text-sm text-gray-900 dark:text-white whitespace-pre-wrap">
+                                                {{ $setting['value_display'] }}
+                                            </span>
+                                        @endif
+
+                                        @if(strlen($setting['value_display'] ?? '') > 200)
+                                            <button
+                                                type="button"
+                                                x-data="{ copied: false }"
+                                                x-on:click="
+                                                    navigator.clipboard.writeText('{{ addslashes($setting['value_display']) }}');
+                                                    copied = true;
+                                                    setTimeout(() => copied = false, 2000);
+                                                "
+                                                class="text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition"
+                                                title="Copy value"
+                                            >
+                                                <svg x-show="!copied" class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z"/>
+                                                </svg>
+                                                <svg x-show="copied" x-cloak class="w-4 h-4 text-success-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"/>
+                                                </svg>
+                                            </button>
+                                        @endif
+                                    </div>
+
+                                    @if(!empty($setting['help_text']))
+                                        <p class="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                                            {{ Str::limit($setting['help_text'], 150) }}
+                                        </p>
+                                    @endif
+                                </dd>
+                            </div>
+                        @endforeach
+                    </dl>
+                </x-filament::section>
+            @endif
+        @endforeach
+
+        @if(collect($groups)->sum(fn($g) => count(collect($g['settings'] ?? [])->filter(function($s) use ($searchQuery) {
+            if (empty($searchQuery)) return true;
+            $searchLower = strtolower($searchQuery);
+            return str_contains(strtolower($s['label'] ?? ''), $searchLower) ||
+                   str_contains(strtolower($s['value_display'] ?? ''), $searchLower);
+        }))) === 0)
+            <div class="text-center py-8">
+                <p class="text-gray-500 dark:text-gray-400">No settings match your search</p>
+                <button
+                    type="button"
+                    wire:click="$set('search', '')"
+                    class="mt-2 text-sm text-primary-600 hover:text-primary-700 dark:text-primary-400"
+                >
+                    Clear search
+                </button>
+            </div>
+        @endif
+    @endif
+</div>

resources/views/filament/infolists/entries/snapshot-json.blade.php

@@ -1,20 +1,26 @@
 @php
+    // Obtain state from Filament infolist entry
     $payload = $getState();
-    $json = is_string($payload) ? $payload : json_encode($payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
+
+    // Normalize payload to array for the JSON viewer
+    $payloadArray = is_string($payload) ? (json_decode($payload, true) ?? []) : ($payload ?? []);
+
+    // Provide the small set of helpers the pepperfm json view expects
+    $getState = fn () => $payloadArray;
+    $getCharacterLimit = fn () => null;
+    $getAsModal = fn () => false;
+    $getAsDrawer = fn () => false;
+    $getKeyColumnLabel = fn () => 'Key';
+    $getValueColumnLabel = fn () => 'Value';
+    $getButtonConfig = fn () => (object) ['id' => 'fj-modal', 'icon' => null, 'iconColor' => null, 'alignment' => null, 'width' => null, 'closeByClickingAway' => true, 'closedByEscaping' => true, 'closedButton' => true, 'label' => null, 'tooltip' => null, 'size' => null, 'href' => null, 'tag' => null, 'color' => null];
+    $getModalConfig = fn () => (object) ['id' => 'fj-modal', 'icon' => null, 'iconColor' => null, 'alignment' => null, 'width' => null, 'closeByClickingAway' => true, 'closedByEscaping' => true, 'closedButton' => true];
+    $getRenderMode = fn () => \PepperFM\FilamentJson\Enums\RenderModeEnum::Tree;
+    $getInitiallyCollapsed = fn () => 1;
+    $getExpandAllToggle = fn () => false;
+    $getCopyJsonAction = fn () => true;
+    $getMaxDepth = fn () => 3;
+    $applyLimit = fn ($v) => $v;
 @endphp
 
-<div class="space-y-2">
+{{-- Render pepperfm filament-json viewer --}}
-    <div class="flex items-center justify-between text-sm font-semibold text-gray-800">
+@include('filament-json::json')
-        <span>Raw JSON</span>
-        <button
-            type="button"
-            x-data
-            @click="navigator.clipboard.writeText(@js($json ?? ''))"
-            class="text-xs font-medium text-blue-600 hover:text-blue-800"
-        >
-            Copy
-        </button>
-    </div>
-
-    <pre class="overflow-x-auto rounded border border-gray-200 bg-gray-50 p-3 text-xs text-gray-800"><code class="language-json">{{ $json }}</code></pre>
-</div>

resources/views/filament/modals/settings-catalog-setting-details.blade.php

@@ -0,0 +1,70 @@
+@php
+    $definition = $record['definition'] ?? '-';
+    $type = $record['type'] ?? '-';
+    $value = $record['value'] ?? '-';
+    $path = $record['path'] ?? '-';
+    $raw = $record['raw'] ?? null;
+    $rawJson = is_array($raw) ? json_encode($raw, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) : null;
+@endphp
+
+<div class="space-y-4">
+    <div class="grid grid-cols-1 gap-3">
+        <div class="rounded-lg border border-gray-200 bg-white p-3 shadow-sm dark:border-white/10 dark:bg-white/5">
+            <div class="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-300">Definition</div>
+            <div class="mt-1 flex items-start justify-between gap-3">
+                <div class="break-all font-mono text-xs text-gray-800 dark:text-gray-100">{{ $definition }}</div>
+                <button
+                    type="button"
+                    x-data
+                    @click="navigator.clipboard.writeText(@js($definition))"
+                    class="shrink-0 text-xs font-medium text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300"
+                >
+                    Copy
+                </button>
+            </div>
+        </div>
+
+        <div class="rounded-lg border border-gray-200 bg-white p-3 shadow-sm dark:border-white/10 dark:bg-white/5">
+            <div class="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-300">Type</div>
+            <div class="mt-1 break-all font-mono text-xs text-gray-800 dark:text-gray-100">{{ $type }}</div>
+        </div>
+
+        <div class="rounded-lg border border-gray-200 bg-white p-3 shadow-sm dark:border-white/10 dark:bg-white/5">
+            <div class="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-300">Value</div>
+            <div class="mt-1 flex items-start justify-between gap-3">
+                <div class="whitespace-pre-wrap break-words text-sm text-gray-800 dark:text-gray-100">{{ $value }}</div>
+                <button
+                    type="button"
+                    x-data
+                    @click="navigator.clipboard.writeText(@js($value))"
+                    class="shrink-0 text-xs font-medium text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300"
+                >
+                    Copy
+                </button>
+            </div>
+        </div>
+
+        <div class="rounded-lg border border-gray-200 bg-white p-3 shadow-sm dark:border-white/10 dark:bg-white/5">
+            <div class="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-300">Path</div>
+            <div class="mt-1 break-all font-mono text-xs text-gray-800 dark:text-gray-100">{{ $path }}</div>
+        </div>
+    </div>
+
+    @if ($rawJson)
+        <div class="rounded-lg border border-gray-200 bg-gray-50 p-3 dark:border-white/10 dark:bg-white/5">
+            <div class="mb-2 flex items-center justify-between text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-300">
+                <span>Raw</span>
+                <button
+                    type="button"
+                    x-data
+                    @click="navigator.clipboard.writeText(@js($rawJson))"
+                    class="text-xs font-medium text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300"
+                >
+                    Copy
+                </button>
+            </div>
+            <pre class="max-h-[420px] overflow-auto text-xs font-mono leading-relaxed text-gray-800 dark:text-gray-100"><code class="language-json">{{ $rawJson }}</code></pre>
+        </div>
+    @endif
+</div>
+

resources/views/livewire/settings-catalog-settings-table.blade.php

@@ -0,0 +1,5 @@
+<div class="space-y-2">
+    <div class="overflow-x-auto">
+        {{ $this->table }}
+    </div>
+</div>

specs/185-settings-catalog-readable/IMPLEMENTATION_STATUS.md

@@ -0,0 +1,469 @@
+# Feature 185: Implementation Status Report
+
+## Executive Summary
+
+**Status**: ✅ **Core Implementation Complete** (Phases 1-5)  
+**Date**: 2025-12-13  
+**Remaining Work**: Testing & Manual Verification (Phases 6-7)
+
+## Implementation Progress
+
+### ✅ Completed Phases (1-5)
+
+#### Phase 1: Database Foundation
+- ✅ T001: Migration created and applied successfully (73.61ms)
+- ✅ T002: SettingsCatalogDefinition model with helper methods
+- **Result**: `settings_catalog_definitions` table exists with GIN index on JSONB
+
+#### Phase 2: Definition Resolver Service
+- ✅ T003-T007: Complete SettingsCatalogDefinitionResolver service
+- **Features**:
+  - 3-tier caching: Memory → Database (30 days) → Graph API
+  - Batch resolution with `$filter=id in (...)` optimization
+  - Non-blocking cache warming with error handling
+  - Graceful fallback with prettified definition IDs
+- **File**: `app/Services/Intune/SettingsCatalogDefinitionResolver.php` (267 lines)
+
+#### Phase 3: Snapshot Enrichment
+- ✅ T008-T010: Extended PolicySnapshotService
+- **Features**:
+  - Extracts definition IDs from settings (including nested children)
+  - Calls warmCache() after settings hydration
+  - Adds metadata: `definition_count`, `definitions_cached`
+- **File**: `app/Services/Intune/PolicySnapshotService.php` (extended)
+
+#### Phase 4: Normalizer Enhancement
+- ✅ T011-T014: Extended PolicyNormalizer
+- **Features**:
+  - `normalizeSettingsCatalogGrouped()` main method
+  - Value formatting: bool → badges, int → formatted, string → truncated
+  - Grouping by categoryId with fallback to definition ID segments
+  - Recursive flattening of nested group settings
+  - Alphabetical sorting of groups
+- **File**: `app/Services/Intune/PolicyNormalizer.php` (extended with 8 new methods)
+
+#### Phase 5: UI Implementation
+- ✅ T015-T022: Complete Settings tab with grouped accordion view
+- **Features**:
+  - Filament Section components for collapsible groups
+  - First group expanded by default
+  - Setting rows with labels, formatted values, help text
+  - Alpine.js copy buttons with clipboard API
+  - Client-side search filtering
+  - Empty states and fallback warnings
+  - Dark mode support
+- **Files**:
+  - `resources/views/filament/infolists/entries/settings-catalog-grouped.blade.php` (~130 lines)
+  - `app/Filament/Resources/PolicyResource.php` (Settings tab extended)
+
+### ⏳ Pending Phases (6-7)
+
+#### Phase 6: Manual Verification (T023-T025)
+- [ ] T023: Verify JSON tab still works
+- [ ] T024: Verify fallback message for uncached definitions
+- [ ] T025: Ensure JSON viewer scoped to Policy View only
+
+**Estimated Time**: ~15 minutes  
+**Action Required**: Navigate to `/admin/policies/{id}` for Settings Catalog policy
+
+#### Phase 7: Testing & Validation (T026-T042)
+- [ ] T026-T031: Unit tests (SettingsCatalogDefinitionResolverTest, PolicyNormalizerSettingsCatalogTest)
+- [ ] T032-T037: Feature tests (PolicyViewSettingsCatalogReadableTest)
+- [ ] T038-T039: Pest suite execution, Pint formatting
+- [ ] T040-T042: Git review, migration check, manual QA walkthrough
+
+**Estimated Time**: ~4-5 hours  
+**Action Required**: Write comprehensive test coverage
+
+---
+
+## Code Quality Verification
+
+### ✅ Laravel Pint
+- **Status**: PASS - 32 files formatted
+- **Command**: `./vendor/bin/sail pint --dirty`
+- **Result**: All code compliant with Laravel coding standards
+
+### ✅ Cache Management
+- **Command**: `./vendor/bin/sail artisan optimize:clear`
+- **Result**: All caches cleared (config, views, routes, Blade, Filament)
+
+### ✅ Database Migration
+- **Command**: `./vendor/bin/sail artisan migrate`
+- **Result**: `settings_catalog_definitions` table exists
+- **Verification**: `Schema::hasTable('settings_catalog_definitions')` returns `true`
+
+---
+
+## Architecture Overview
+
+### Service Layer
+
+```
+PolicySnapshotService
+    ↓ (extracts definition IDs)
+SettingsCatalogDefinitionResolver
+    ↓ (resolves definitions)
+PolicyNormalizer
+    ↓ (groups & formats)
+PolicyResource (Filament)
+    ↓ (renders)
+settings-catalog-grouped.blade.php
+```
+
+### Caching Strategy
+
+```
+Request
+    ↓
+Memory Cache (Laravel Cache, request-level)
+    ↓ (miss)
+Database Cache (30 days TTL)
+    ↓ (miss)
+Graph API (/deviceManagement/configurationSettings)
+    ↓ (store)
+Database + Memory
+    ↓ (fallback on Graph failure)
+Prettified Definition ID
+```
+
+### UI Flow
+
+```
+Policy View (Filament)
+    ↓
+Tabs: Settings | JSON
+    ↓ (Settings tab)
+Check metadata.definitions_cached
+    ↓ (true)
+settings_grouped ViewEntry
+    ↓
+normalizeSettingsCatalogGrouped()
+    ↓
+Blade Component
+    ↓
+Accordion Groups (Filament Sections)
+    ↓
+Setting Rows (label, value, help text, copy button)
+```
+
+---
+
+## Files Created/Modified
+
+### Created Files (5)
+
+1. **database/migrations/2025_12_13_212126_create_settings_catalog_definitions_table.php**
+   - Purpose: Cache setting definitions from Graph API
+   - Schema: 9 columns + timestamps, GIN index on JSONB
+   - Status: ✅ Applied (73.61ms)
+
+2. **app/Models/SettingsCatalogDefinition.php**
+   - Purpose: Eloquent model for cached definitions
+   - Methods: `findByDefinitionId()`, `findByDefinitionIds()`
+   - Status: ✅ Complete
+
+3. **app/Services/Intune/SettingsCatalogDefinitionResolver.php**
+   - Purpose: Fetch and cache definitions with 3-tier strategy
+   - Lines: 267
+   - Methods: `resolve()`, `resolveOne()`, `warmCache()`, `clearCache()`, `prettifyDefinitionId()`
+   - Status: ✅ Complete with error handling
+
+4. **resources/views/filament/infolists/entries/settings-catalog-grouped.blade.php**
+   - Purpose: Blade template for grouped settings accordion
+   - Lines: ~130
+   - Features: Alpine.js interactivity, Filament Sections, search filtering
+   - Status: ✅ Complete with dark mode support
+
+5. **specs/185-settings-catalog-readable/** (Directory with 3 files)
+   - `spec.md` - Complete feature specification
+   - `plan.md` - Implementation plan
+   - `tasks.md` - 42 tasks with FR traceability
+   - Status: ✅ Complete with implementation notes
+
+### Modified Files (3)
+
+1. **app/Services/Intune/PolicySnapshotService.php**
+   - Changes: Added `SettingsCatalogDefinitionResolver` injection
+   - New method: `extractDefinitionIds()` (recursive extraction)
+   - Extended method: `hydrateSettingsCatalog()` (cache warming + metadata)
+   - Status: ✅ Extended without breaking existing functionality
+
+2. **app/Services/Intune/PolicyNormalizer.php**
+   - Changes: Added `SettingsCatalogDefinitionResolver` injection
+   - New methods: 8 methods (~200 lines)
+     - `normalizeSettingsCatalogGrouped()` (main entry point)
+     - `extractAllDefinitionIds()`, `flattenSettingsCatalogForGrouping()`
+     - `formatSettingsCatalogValue()`, `groupSettingsByCategory()`
+     - `extractCategoryFromDefinitionId()`, `formatCategoryTitle()`
+   - Status: ✅ Extended with comprehensive formatting/grouping logic
+
+3. **app/Filament/Resources/PolicyResource.php**
+   - Changes: Extended Settings tab in `policy_content` Tabs
+   - New entries:
+     - `settings_grouped` ViewEntry (uses Blade component)
+     - `definitions_not_cached` TextEntry (fallback message)
+   - Conditional rendering: Grouped view only if `definitions_cached === true`
+   - Status: ✅ Extended Settings tab, JSON tab preserved
+
+---
+
+## Verification Checklist (Pre-Testing)
+
+### ✅ Code Quality
+- [X] Laravel Pint passed (32 files)
+- [X] All code formatted with PSR-12 conventions
+- [X] No Pint warnings or errors
+
+### ✅ Database
+- [X] Migration applied successfully
+- [X] Table exists with correct schema
+- [X] Indexes created (definition_id unique, category_id, GIN on raw)
+
+### ✅ Service Injection
+- [X] SettingsCatalogDefinitionResolver registered in service container
+- [X] PolicySnapshotService constructor updated
+- [X] PolicyNormalizer constructor updated
+- [X] Laravel auto-resolves dependencies
+
+### ✅ Caching
+- [X] All caches cleared (config, views, routes, Blade, Filament)
+- [X] Blade component compiled
+- [X] Filament schema cache refreshed
+
+### ✅ UI Integration
+- [X] Settings tab extended with grouped view
+- [X] JSON tab preserved from Feature 002
+- [X] Conditional rendering based on metadata
+- [X] Fallback message implemented
+
+### ⏳ Manual Verification Pending
+- [ ] Navigate to Policy View for Settings Catalog policy
+- [ ] Verify accordion renders with groups
+- [ ] Verify display names shown (not raw definition IDs)
+- [ ] Verify values formatted (badges, numbers, truncated strings)
+- [ ] Test search filtering
+- [ ] Test copy buttons
+- [ ] Switch to JSON tab, verify snapshot renders
+- [ ] Test fallback for policy without cached definitions
+- [ ] Test dark mode toggle
+
+### ⏳ Testing Pending
+- [ ] Unit tests written and passing
+- [ ] Feature tests written and passing
+- [ ] Performance benchmarks validated
+
+---
+
+## Next Steps (Priority Order)
+
+### Immediate (Phase 6 - Manual Verification)
+
+1. **Open Policy View** (5 min)
+   - Navigate to `/admin/policies/{id}` for Settings Catalog policy
+   - Verify page loads without errors
+   - Check browser console for JavaScript errors
+
+2. **Verify Tabs & Accordion** (5 min)
+   - Confirm "Settings" and "JSON" tabs visible
+   - Click Settings tab, verify accordion renders
+   - Verify groups collapsible (first expanded by default)
+   - Click JSON tab, verify snapshot renders with copy button
+
+3. **Verify Display & Formatting** (5 min)
+   - Check setting labels show display names (not `device_vendor_msft_...`)
+   - Verify bool values show as "Enabled"/"Disabled" badges (green/gray)
+   - Verify int values formatted with separators (e.g., "1,000")
+   - Verify long strings truncated with "..." and copy button
+
+4. **Test Search & Fallback** (5 min)
+   - Type in search box (if visible), verify filtering works
+   - Test copy buttons (long values)
+   - Find policy WITHOUT cached definitions
+   - Verify fallback message: "Definitions not yet cached..."
+   - Verify JSON tab still accessible
+
+**Total Estimated Time**: ~20 minutes
+
+### Short-Term (Phase 7 - Unit Tests)
+
+1. **Create Unit Tests** (2-3 hours)
+   - `tests/Unit/SettingsCatalogDefinitionResolverTest.php`
+     - Test `resolve()` with batch IDs
+     - Test memory cache hit
+     - Test database cache hit
+     - Test Graph API fetch
+     - Test fallback prettification
+     - Test non-blocking warmCache()
+   - `tests/Unit/PolicyNormalizerSettingsCatalogTest.php`
+     - Test `normalizeSettingsCatalogGrouped()` output structure
+     - Test value formatting (bool, int, string, choice)
+     - Test grouping by categoryId
+     - Test fallback grouping by definition ID segments
+     - Test recursive definition ID extraction
+
+2. **Create Feature Tests** (2 hours)
+   - `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+     - Test Settings Catalog policy view shows tabs
+     - Test Settings tab shows display names (not definition IDs)
+     - Test values formatted correctly (badges, numbers, truncation)
+     - Test search filters settings
+     - Test fallback message when definitions not cached
+     - Test JSON tab still accessible
+
+3. **Run Test Suite** (15 min)
+   - `./vendor/bin/sail artisan test --filter=SettingsCatalog`
+   - Fix any failures
+   - Verify all tests pass
+
+**Total Estimated Time**: ~5 hours
+
+### Medium-Term (Performance & Polish)
+
+1. **Performance Testing** (1 hour)
+   - Create test policy with 200+ settings
+   - Measure render time (target: <2s)
+   - Measure definition resolution time (target: <500ms for 50 cached)
+   - Profile with Laravel Telescope or Debugbar
+
+2. **Manual QA Walkthrough** (1 hour)
+   - Test all user stories (US-UI-04, US-UI-05, US-UI-06)
+   - Verify all success criteria (SC-001 to SC-010)
+   - Test dark mode toggle
+   - Test with different policy types
+   - Document any issues or enhancements
+
+**Total Estimated Time**: ~2 hours
+
+---
+
+## Risk Assessment
+
+### ✅ Mitigated Risks
+
+- **Graph API Rate Limiting**: Non-blocking cache warming prevents snapshot save failures
+- **Definition Schema Changes**: Raw JSONB storage allows future parsing updates
+- **Large Policy Rendering**: Accordion lazy-loading via Filament Sections
+- **Missing Definitions**: Multi-layer fallback (prettified IDs → warning badges → info messages)
+
+### ⚠️ Outstanding Risks
+
+- **Performance with 500+ Settings**: Not tested yet (Phase 7, T042)
+- **Graph API Downtime**: Cache helps, but first sync may fail (acceptable trade-off)
+- **Browser Compatibility**: Alpine.js clipboard API requires HTTPS (Dokploy provides SSL)
+
+### ℹ️ Known Limitations
+
+- **Search**: Client-side only (Blade-level filtering), no debouncing for large policies
+- **Value Expansion**: Long strings truncated, no inline expansion (copy button only)
+- **Nested Groups**: Flattened in UI, hierarchy not visually preserved
+
+---
+
+## Constitution Compliance
+
+### ✅ Safety-First
+- Read-only feature, no edit capabilities
+- Graceful degradation at every layer
+- Non-blocking operations (warmCache)
+
+### ✅ Immutable Versioning
+- Snapshot enrichment adds metadata only
+- No modification of existing snapshot data
+- Definition cache separate from policy snapshots
+
+### ✅ Defensive Restore
+- Not applicable (read-only feature)
+
+### ✅ Auditability
+- Raw JSON still accessible via JSON tab
+- Definition resolution logged via Laravel Log
+- Graph API calls auditable via GraphLogger
+
+### ✅ Tenant-Aware
+- Resolver respects tenant scoping via GraphClient
+- Definitions scoped per tenant (via Graph API calls)
+
+### ✅ Graph Abstraction
+- Uses existing GraphClientInterface (no direct MS Graph SDK calls)
+- Follows existing abstraction patterns
+
+### ✅ Spec-Driven
+- Full spec + plan + tasks before implementation
+- FR→Task traceability maintained
+- Implementation notes added to tasks.md
+
+---
+
+## Deployment Readiness
+
+### ✅ Local Development (Laravel Sail)
+- [X] Database migration applied
+- [X] Services registered in container
+- [X] Caches cleared
+- [X] Code formatted with Pint
+- [X] Table exists with data ready for seeding
+
+### ⏳ Staging Deployment (Dokploy)
+- [ ] Run migrations: `php artisan migrate`
+- [ ] Clear caches: `php artisan optimize:clear`
+- [ ] Verify environment variables (none required for Feature 185)
+- [ ] Test with real Intune tenant data
+- [ ] Monitor Graph API rate limits
+
+### ⏳ Production Deployment (Dokploy)
+- [ ] Complete staging validation
+- [ ] Feature flag enabled (if applicable)
+- [ ] Monitor performance metrics
+- [ ] Document rollback plan (drop table, revert code)
+
+---
+
+## Support Information
+
+### Troubleshooting Guide
+
+**Issue**: Settings tab shows raw definition IDs instead of display names
+- **Cause**: Definitions not cached yet
+- **Solution**: Wait for next policy sync (SyncPoliciesJob) or manually trigger sync
+
+**Issue**: Accordion doesn't render, blank Settings tab
+- **Cause**: JavaScript error in Blade component
+- **Solution**: Check browser console for errors, verify Alpine.js loaded
+
+**Issue**: "Definitions not cached" message persists
+- **Cause**: Graph API call failed during snapshot
+- **Solution**: Check logs for Graph API errors, verify permissions for `/deviceManagement/configurationSettings` endpoint
+
+**Issue**: Performance slow with large policies
+- **Cause**: Too many settings rendered at once
+- **Solution**: Consider pagination or virtual scrolling (future enhancement)
+
+### Maintenance Tasks
+
+- **Cache Clearing**: Run `php artisan cache:clear` if definitions stale
+- **Database Cleanup**: Run `SettingsCatalogDefinition::where('updated_at', '<', now()->subDays(30))->delete()` to prune old definitions
+- **Performance Monitoring**: Watch `policy_view` page load times in Telescope
+
+---
+
+## Conclusion
+
+**Implementation Status**: ✅ **CORE COMPLETE**
+
+Phases 1-5 implemented successfully with:
+- ✅ Database schema + model
+- ✅ Definition resolver with 3-tier caching
+- ✅ Snapshot enrichment with cache warming
+- ✅ Normalizer with grouping/formatting
+- ✅ UI with accordion, search, and fallback
+
+**Next Action**: **Phase 6 Manual Verification** (~20 min)
+
+Navigate to Policy View and verify all features work as expected before proceeding to Phase 7 testing.
+
+**Estimated Remaining Work**: ~7 hours
+- Phase 6: ~20 min
+- Phase 7: ~5-7 hours (tests + QA)
+
+**Feature Delivery Target**: Ready for staging deployment after Phase 7 completion.

specs/185-settings-catalog-readable/MANUAL_VERIFICATION_GUIDE.md

@@ -0,0 +1,312 @@
+# Feature 185: Manual Verification Guide (Phase 6)
+
+## Quick Start
+
+**Estimated Time**: 20 minutes  
+**Prerequisites**: Settings Catalog policy exists in database with snapshot
+
+---
+
+## Verification Steps
+
+### Step 1: Navigate to Policy View (2 min)
+
+1. Open browser: `http://localhost` (or your Sail URL)
+2. Login to Filament admin panel
+3. Navigate to **Policies** resource
+4. Click on a **Settings Catalog** policy (look for `settingsCatalogPolicy` type)
+
+**Expected Result**:
+- ✅ Page loads without errors
+- ✅ Policy details visible
+- ✅ No browser console errors
+
+**If it fails**:
+- Check browser console for JavaScript errors
+- Run `./vendor/bin/sail artisan optimize:clear`
+- Verify policy has `versions` relationship loaded
+
+---
+
+### Step 2: Verify Tabs Present (2 min)
+
+**Action**: Look at the Policy View infolist
+
+**Expected Result**:
+- ✅ "Settings" tab visible
+- ✅ "JSON" tab visible
+- ✅ Settings tab is default (active)
+
+**If tabs missing**:
+- Check if policy is actually Settings Catalog type
+- Verify PolicyResource.php has Tabs component for `policy_content`
+- Check Feature 002 JSON viewer implementation
+
+---
+
+### Step 3: Verify Settings Tab - Accordion (5 min)
+
+**Action**: Click on "Settings" tab (if not already active)
+
+**Expected Result**:
+- ✅ Accordion groups render
+- ✅ Each group has:
+  - Title (e.g., "Device Vendor Msft", "Biometric Authentication")
+  - Description (if available)
+  - Setting count badge (e.g., "12 settings")
+- ✅ First group expanded by default
+- ✅ Other groups collapsed
+- ✅ Click group header toggles collapse/expand
+
+**If accordion missing**:
+- Check if `metadata.definitions_cached === true` in snapshot
+- Verify normalizer returns groups structure
+- Check Blade component exists: `settings-catalog-grouped.blade.php`
+
+---
+
+### Step 4: Verify Display Names (Not Definition IDs) (3 min)
+
+**Action**: Expand a group and look at setting labels
+
+**Expected Result**:
+- ✅ Labels show human-readable names:
+  - ✅ "Biometric Authentication" (NOT `device_vendor_msft_policy_biometric_authentication`)
+  - ✅ "Password Minimum Length" (NOT `device_vendor_msft_policy_password_minlength`)
+- ✅ No `device_vendor_msft_...` visible in labels
+
+**If definition IDs visible**:
+- Check if definitions cached in database: `SettingsCatalogDefinition::count()`
+- Run policy sync manually to trigger cache warming
+- Verify fallback message visible: "Definitions not yet cached..."
+
+---
+
+### Step 5: Verify Value Formatting (5 min)
+
+**Action**: Look at setting values in different groups
+
+**Expected Result**:
+- ✅ **Boolean values**: Badges with "Enabled" (green) or "Disabled" (gray)
+- ✅ **Integer values**: Formatted with separators (e.g., "1,000" not "1000")
+- ✅ **String values**: Truncated if >100 chars with "..."
+- ✅ **Choice values**: Show choice label (not raw ID)
+
+**If formatting incorrect**:
+- Check `formatSettingsCatalogValue()` method in PolicyNormalizer
+- Verify Blade component conditionals for value types
+- Inspect browser to see actual rendered HTML
+
+---
+
+### Step 6: Test Copy Buttons (2 min)
+
+**Action**: Find a setting with a long value, click copy button
+
+**Expected Result**:
+- ✅ Copy button visible for long values
+- ✅ Click copy button → clipboard receives value
+- ✅ Button shows checkmark for 2 seconds
+- ✅ Button returns to copy icon after timeout
+
+**If copy button missing/broken**:
+- Check Alpine.js loaded (inspect page source for `@livewireScripts`)
+- Verify clipboard API available (requires HTTPS or localhost)
+- Check browser console for JavaScript errors
+
+---
+
+### Step 7: Test Search Filtering (Optional - if search visible) (2 min)
+
+**Action**: Type in search box (if visible at top of Settings tab)
+
+**Expected Result**:
+- ✅ Search box visible with placeholder "Search settings..."
+- ✅ Type search query (e.g., "biometric")
+- ✅ Only matching settings shown
+- ✅ Non-matching groups hidden/empty
+- ✅ Clear search resets view
+
+**If search not visible**:
+- This is expected for MVP (Blade-level implementation, no dedicated input yet)
+- Search logic exists in Blade template but may need Livewire wiring
+
+---
+
+### Step 8: Verify JSON Tab (2 min)
+
+**Action**: Click "JSON" tab
+
+**Expected Result**:
+- ✅ Tab switches to JSON view
+- ✅ Snapshot renders with syntax highlighting
+- ✅ Copy button visible at top
+- ✅ Click copy button → full JSON copied to clipboard
+- ✅ Can switch back to Settings tab
+
+**If JSON tab broken**:
+- Verify Feature 002 implementation still intact
+- Check `pepperfm/filament-json` package installed
+- Verify PolicyResource.php has JSON ViewEntry
+
+---
+
+### Step 9: Test Fallback Message (3 min)
+
+**Action**: Find a Settings Catalog policy WITHOUT cached definitions (or manually delete definitions from database)
+
+**Steps to test**:
+1. Run: `./vendor/bin/sail artisan tinker`
+2. Execute: `\App\Models\SettingsCatalogDefinition::truncate();`
+3. Navigate to Policy View for Settings Catalog policy
+4. Click Settings tab
+
+**Expected Result**:
+- ✅ Settings tab shows fallback message:
+  - "Definitions not yet cached. Settings will be shown with raw IDs."
+  - Helper text: "Switch to JSON tab or wait for next sync"
+- ✅ JSON tab still accessible
+- ✅ No error messages or broken layout
+
+**If fallback not visible**:
+- Check conditional rendering in PolicyResource.php
+- Verify `metadata.definitions_cached` correctly set in snapshot
+- Check Blade component has fallback TextEntry
+
+---
+
+### Step 10: Test Dark Mode (Optional) (2 min)
+
+**Action**: Toggle Filament dark mode (if available)
+
+**Expected Result**:
+- ✅ Accordion groups adjust colors
+- ✅ Badges adjust colors (dark mode variants)
+- ✅ Text remains readable
+- ✅ No layout shifts or broken styles
+
+**If dark mode broken**:
+- Check Blade component uses `dark:` Tailwind classes
+- Verify Filament Section components support dark mode
+- Inspect browser to see actual computed styles
+
+---
+
+## Success Criteria Checklist
+
+After completing all steps, mark these off:
+
+- [ ] **T023**: JSON tab works (from Feature 002)
+- [ ] **T024**: Fallback message shows when definitions not cached
+- [ ] **T025**: JSON viewer only renders on Policy View (not globally)
+
+---
+
+## Common Issues & Solutions
+
+### Issue: "Definitions not yet cached" persists
+
+**Cause**: SyncPoliciesJob hasn't run yet or Graph API call failed
+
+**Solution**:
+1. Manually trigger sync:
+   ```bash
+   ./vendor/bin/sail artisan tinker
+   ```
+   ```php
+   $policy = \App\Models\Policy::first();
+   \App\Jobs\SyncPoliciesJob::dispatch();
+   ```
+2. Check logs for Graph API errors:
+   ```bash
+   ./vendor/bin/sail artisan log:show
+   ```
+
+### Issue: Accordion doesn't render
+
+**Cause**: Blade component error or missing groups
+
+**Solution**:
+1. Check browser console for errors
+2. Verify normalizer output:
+   ```bash
+   ./vendor/bin/sail artisan tinker
+   ```
+   ```php
+   $policy = \App\Models\Policy::first();
+   $snapshot = $policy->versions()->orderByDesc('captured_at')->value('snapshot');
+   $normalizer = app(\App\Services\Intune\PolicyNormalizer::class);
+   $groups = $normalizer->normalizeSettingsCatalogGrouped($snapshot['settings'] ?? []);
+   dd($groups);
+   ```
+
+### Issue: Copy buttons don't work
+
+**Cause**: Alpine.js not loaded or clipboard API unavailable
+
+**Solution**:
+1. Verify Alpine.js loaded:
+   - Open browser console
+   - Type `window.Alpine` → should return object
+2. Check HTTPS or localhost (clipboard API requires secure context)
+3. Fallback: Use "View JSON" tab and copy from there
+
+---
+
+## Next Steps After Verification
+
+### If All Tests Pass ✅
+
+Proceed to **Phase 7: Testing & Validation**
+
+1. Write unit tests (T026-T031)
+2. Write feature tests (T032-T037)
+3. Run Pest suite (T038-T039)
+4. Manual QA walkthrough (T040-T042)
+
+**Estimated Time**: ~5-7 hours
+
+### If Issues Found ⚠️
+
+1. Document issues in `specs/185-settings-catalog-readable/ISSUES.md`
+2. Fix critical issues (broken UI, errors)
+3. Re-run verification steps
+4. Proceed to Phase 7 only after verification passes
+
+---
+
+## Reporting Results
+
+After completing verification, update tasks.md:
+
+```bash
+# Mark T023-T025 as complete
+vim specs/185-settings-catalog-readable/tasks.md
+```
+
+Add implementation notes:
+```markdown
+- [X] **T023** Verify JSON tab still works
+  - **Implementation Note**: Verified tabs functional, JSON viewer renders snapshot
+
+- [X] **T024** Add fallback for policies without cached definitions
+  - **Implementation Note**: Fallback message shows info with guidance to JSON tab
+
+- [X] **T025** Ensure JSON viewer only renders on Policy View
+  - **Implementation Note**: Verified scoping correct, only shows on Policy resource
+```
+
+---
+
+## Contact & Support
+
+If verification fails or you need assistance:
+
+1. Check logs: `./vendor/bin/sail artisan log:show`
+2. Review implementation status: `specs/185-settings-catalog-readable/IMPLEMENTATION_STATUS.md`
+3. Review code: `app/Services/Intune/`, `app/Filament/Resources/PolicyResource.php`
+4. Ask for help with specific error messages and context
+
+---
+
+**End of Manual Verification Guide**

specs/185-settings-catalog-readable/plan.md

@@ -0,0 +1,414 @@
+# Feature 185: Implementation Plan
+
+## Tech Stack
+- **Backend**: Laravel 12, PHP 8.4
+- **Database**: PostgreSQL (JSONB for raw definition storage)
+- **Frontend**: Filament 4, Livewire 3, Tailwind CSS
+- **Graph Client**: Existing `GraphClientInterface`
+- **JSON Viewer**: `pepperfm/filament-json` (installed)
+
+## Architecture Overview
+
+### Services Layer
+```
+app/Services/Intune/
+├── SettingsCatalogDefinitionResolver.php  (NEW)
+├── PolicyNormalizer.php                    (EXTEND)
+└── PolicySnapshotService.php               (EXTEND)
+```
+
+### Database Layer
+```
+database/migrations/
+└── xxxx_create_settings_catalog_definitions_table.php  (NEW)
+
+app/Models/
+└── SettingsCatalogDefinition.php  (NEW)
+```
+
+### UI Layer
+```
+app/Filament/Resources/
+├── PolicyResource.php              (EXTEND - infolist with tabs)
+└── PolicyVersionResource.php       (FUTURE - optional)
+
+resources/views/filament/infolists/entries/
+└── settings-catalog-grouped.blade.php  (NEW - accordion view)
+```
+
+## Component Responsibilities
+
+### 1. SettingsCatalogDefinitionResolver
+**Purpose**: Fetch and cache setting definitions from Graph API
+
+**Key Methods**:
+- `resolve(array $definitionIds): array` - Batch resolve definitions
+- `resolveOne(string $definitionId): ?array` - Single definition lookup
+- `warmCache(array $definitionIds): void` - Pre-populate cache
+- `clearCache(?string $definitionId = null): void` - Cache invalidation
+
+**Dependencies**:
+- `GraphClientInterface` - Graph API calls
+- `SettingsCatalogDefinition` model - Database cache
+- Laravel Cache - Memory-level cache
+
+**Caching Strategy**:
+1. Check memory cache (request-level)
+2. Check database cache (30-day TTL)
+3. Fetch from Graph API
+4. Store in DB + memory
+
+**Graph Endpoints**:
+- `/deviceManagement/configurationSettings` (global catalog)
+- `/deviceManagement/configurationPolicies/{id}/settings/{settingId}/settingDefinitions` (policy-specific)
+
+### 2. PolicyNormalizer (Extension)
+**Purpose**: Transform Settings Catalog snapshot into UI-ready structure
+
+**New Method**: `normalizeSettingsCatalog(array $snapshot, array $definitions): array`
+
+**Output Structure**:
+```php
+[
+    'type' => 'settings_catalog',
+    'groups' => [
+        [
+            'title' => 'Windows Hello for Business',
+            'description' => 'Configure biometric authentication settings',
+            'settings' => [
+                [
+                    'label' => 'Use biometrics',
+                    'value_display' => 'Enabled',
+                    'value_raw' => true,
+                    'help_text' => 'Allow users to sign in with fingerprint...',
+                    'definition_id' => 'device_vendor_msft_passportforwork_biometrics_usebiometrics',
+                    'instance_type' => 'ChoiceSettingInstance'
+                ]
+            ]
+        ]
+    ]
+]
+```
+
+**Value Formatting Rules**:
+- `ChoiceSettingInstance`: Extract choice label from `@odata.type` or value
+- `SimpleSetting` (bool): "Enabled" / "Disabled"
+- `SimpleSetting` (int): Number formatted with separators
+- `SimpleSetting` (string): Truncate >100 chars, add "..."
+- `GroupSettingCollectionInstance`: Flatten children recursively
+
+**Grouping Strategy**:
+- Group by `categoryId` from definition metadata
+- Fallback: Group by first segment of definition ID (e.g., `device_vendor_msft_`)
+- Sort groups alphabetically
+
+### 3. PolicySnapshotService (Extension)
+**Purpose**: Enrich snapshots with definition metadata after hydration
+
+**Modified Flow**:
+```
+1. Hydrate settings from Graph (existing)
+2. Extract all settingDefinitionId + children (NEW)
+3. Call SettingsCatalogDefinitionResolver::warmCache() (NEW)
+4. Add metadata to snapshot: definitions_cached, definition_count (NEW)
+5. Save snapshot (existing)
+```
+
+**Non-Blocking**: Definition resolution should not block policy sync
+- Use try/catch for Graph API calls
+- Mark `definitions_cached: false` on failure
+- Continue with snapshot save
+
+### 4. PolicyResource (UI Extension)
+**Purpose**: Render Settings Catalog policies with readable UI
+
+**Changes**:
+1. Add Tabs component to infolist:
+   - "Settings" tab (default)
+   - "JSON" tab (existing Feature 002 implementation)
+
+2. Settings Tab Structure:
+   - Search/filter input (top)
+   - Accordion component (groups)
+   - Each group: Section with settings table
+   - Fallback: Show info message if no definitions cached
+
+3. JSON Tab:
+   - Existing implementation from Feature 002
+   - Shows full snapshot with copy button
+
+**Conditional Rendering**:
+- Show tabs ONLY for `settingsCatalogPolicy` type
+- For other policy types: Keep existing simple sections
+
+## Database Schema
+
+### Table: `settings_catalog_definitions`
+```sql
+CREATE TABLE settings_catalog_definitions (
+    id BIGSERIAL PRIMARY KEY,
+    definition_id VARCHAR(500) UNIQUE NOT NULL,
+    display_name VARCHAR(255) NOT NULL,
+    description TEXT,
+    help_text TEXT,
+    category_id VARCHAR(255),
+    ux_behavior VARCHAR(100),
+    raw JSONB NOT NULL,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+
+CREATE INDEX idx_definition_id ON settings_catalog_definitions(definition_id);
+CREATE INDEX idx_category_id ON settings_catalog_definitions(category_id);
+CREATE INDEX idx_raw_gin ON settings_catalog_definitions USING GIN(raw);
+```
+
+**Indexes**:
+- `definition_id` - Primary lookup key
+- `category_id` - Grouping queries
+- `raw` (GIN) - JSONB queries if needed
+
+## Graph API Integration
+
+### Endpoints Used
+
+1. **Global Catalog** (Preferred):
+```
+GET /deviceManagement/configurationSettings
+GET /deviceManagement/configurationSettings/{settingDefinitionId}
+```
+
+2. **Policy-Specific** (Fallback):
+```
+GET /deviceManagement/configurationPolicies/{policyId}/settings/{settingId}/settingDefinitions
+```
+
+### Request Optimization
+- Batch requests where possible
+- Use `$select` to limit fields
+- Use `$filter` for targeted lookups
+- Respect rate limits (429 retry logic)
+
+## UI/UX Flow
+
+### Policy View Page Flow
+1. User navigates to `/admin/policies/{id}`
+2. Policy details loaded (existing)
+3. Check policy type:
+   - If `settingsCatalogPolicy`: Show tabs
+   - Else: Show existing sections
+4. Default to "Settings" tab
+5. Load normalized settings from PolicyNormalizer
+6. Render accordion with groups
+7. User can search/filter settings
+8. User can switch to "JSON" tab for raw view
+
+### Settings Tab Layout
+```
+┌─────────────────────────────────────────────┐
+│ [Search settings...]                    [🔍] │
+├─────────────────────────────────────────────┤
+│ ▼ Windows Hello for Business                │
+│   ├─ Use biometrics: Enabled               │
+│   ├─ Use facial recognition: Disabled      │
+│   └─ PIN minimum length: 6                 │
+├─────────────────────────────────────────────┤
+│ ▼ Device Lock Settings                      │
+│   ├─ Password expiration days: 90          │
+│   └─ Password history: 5                   │
+└─────────────────────────────────────────────┘
+```
+
+### JSON Tab Layout
+```
+┌─────────────────────────────────────────────┐
+│ Full Policy Configuration          [Copy] │
+├─────────────────────────────────────────────┤
+│ {                                           │
+│   "@odata.type": "...",                     │
+│   "name": "WHFB Settings",                  │
+│   "settings": [...]                         │
+│ }                                           │
+└─────────────────────────────────────────────┘
+```
+
+## Error Handling
+
+### Definition Not Found
+- **UI**: Show prettified definition ID
+- **Label**: Convert `device_vendor_msft_policy_name` → "Device Vendor Msft Policy Name"
+- **Icon**: Info icon with tooltip "Definition not cached"
+
+### Graph API Failure
+- **During Sync**: Mark `definitions_cached: false`, continue
+- **During View**: Show cached data or fallback labels
+- **Log**: Record Graph API errors for debugging
+
+### Malformed Snapshot
+- **Validation**: Check for required fields before normalization
+- **Fallback**: Show raw JSON tab, hide Settings tab
+- **Warning**: Display admin-friendly error message
+
+## Performance Considerations
+
+### Database Queries
+- Eager load definitions for all settings in one query
+- Use `whereIn()` for batch lookups
+- Index on `definition_id` ensures fast lookups
+
+### Memory Management
+- Request-level cache using Laravel Cache
+- Limit batch size to 100 definitions per request
+- Clear memory cache after request
+
+### UI Rendering
+- Accordion lazy-loads groups (only render expanded)
+- Pagination for policies with >50 groups
+- Virtualized list for very large policies (future)
+
+### Caching TTL
+- Database: 30 days (definitions change rarely)
+- Memory: Request duration only
+- Background refresh: Optional scheduled job
+
+## Security Considerations
+
+### Graph API Permissions
+- Existing `DeviceManagementConfiguration.Read.All` sufficient
+- No new permissions required
+
+### Data Sanitization
+- Escape HTML in display names and descriptions
+- Validate definition ID format before lookups
+- Prevent XSS in value rendering
+
+### Audit Logging
+- Log definition cache misses
+- Log Graph API failures
+- Track definition cache updates
+
+## Testing Strategy
+
+### Unit Tests
+**File**: `tests/Unit/SettingsCatalogDefinitionResolverTest.php`
+- Test batch resolution
+- Test caching behavior (memory + DB)
+- Test fallback when definition not found
+- Test Graph API error handling
+
+**File**: `tests/Unit/PolicyNormalizerSettingsCatalogTest.php`
+- Test grouping logic
+- Test value formatting (bool, int, choice, string)
+- Test fallback labels
+- Test nested group flattening
+
+### Feature Tests
+**File**: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+- Mock Graph API responses
+- Assert tabs present for Settings Catalog policies
+- Assert display names shown (not definition IDs)
+- Assert values formatted correctly
+- Assert search/filter works
+- Assert JSON tab accessible
+- Assert graceful degradation for missing definitions
+
+### Manual QA Checklist
+1. Open Policy View for Settings Catalog policy
+2. Verify tabs present: "Settings" and "JSON"
+3. Verify Settings tab shows groups with accordion
+4. Verify display names shown (not raw IDs)
+5. Verify values formatted (True/False, numbers, etc.)
+6. Test search: Type setting name, verify filtering
+7. Switch to JSON tab, verify snapshot shown
+8. Test copy button in JSON tab
+9. Test dark mode toggle
+10. Test with policy missing definitions (fallback labels)
+
+## Deployment Steps
+
+### 1. Database Migration
+```bash
+./vendor/bin/sail artisan migrate
+```
+
+### 2. Cache Warming (Optional)
+```bash
+./vendor/bin/sail artisan tinker
+>>> $resolver = app(\App\Services\Intune\SettingsCatalogDefinitionResolver::class);
+>>> $resolver->warmCache([...definitionIds...]);
+```
+
+### 3. Clear Caches
+```bash
+./vendor/bin/sail artisan optimize:clear
+```
+
+### 4. Verify
+- Navigate to Policy View
+- Check browser console for errors
+- Check Laravel logs for Graph API errors
+
+## Rollback Plan
+
+### If Critical Issues Found
+1. Revert database migration:
+   ```bash
+   ./vendor/bin/sail artisan migrate:rollback
+   ```
+
+2. Revert code changes (Git):
+   ```bash
+   git revert <commit-hash>
+   ```
+
+3. Clear caches:
+   ```bash
+   ./vendor/bin/sail artisan optimize:clear
+   ```
+
+### Partial Rollback
+- Remove tabs, keep existing table view
+- Disable definition resolver, show raw IDs
+- Keep database table for future use
+
+## Dependencies on Feature 002
+
+**Shared**:
+- `pepperfm/filament-json` package (installed)
+- JSON viewer CSS assets (published)
+- Tab component pattern (Filament Schemas)
+
+**Independent**:
+- Feature 185 can work without Feature 002 completed
+- Feature 002 provided JSON tab foundation
+- Feature 185 adds Settings tab with readable UI
+
+## Timeline Estimate
+
+- **Phase 1** (Foundation): 2-3 hours
+- **Phase 2** (Snapshot): 1 hour
+- **Phase 3** (Normalizer): 2-3 hours
+- **Phase 4** (UI): 3-4 hours
+- **Phase 5** (Testing): 2-3 hours
+- **Total**: ~11-15 hours
+
+## Success Metrics
+
+1. **User Experience**:
+   - Admins can read policy settings without raw JSON
+   - Search finds settings in <200ms
+   - Accordion groups reduce scrolling
+
+2. **Performance**:
+   - Definition resolution: <500ms for 50 definitions
+   - UI render: <2s for 200 settings
+   - Search response: <200ms
+
+3. **Quality**:
+   - 100% test coverage for resolver
+   - Zero broken layouts for missing definitions
+   - Zero Graph API errors logged (with proper retry)
+
+4. **Adoption**:
+   - Settings tab used >80% of time vs JSON tab
+   - Zero support tickets about "unreadable settings"

specs/185-settings-catalog-readable/spec.md

@@ -0,0 +1,240 @@
+# Feature 185: Intune-like "Cleartext Settings" on Policy View
+
+## Overview
+Display Settings Catalog policies in Policy View with human-readable setting names, descriptions, and formatted values—similar to Intune Portal experience—instead of raw JSON and definition IDs.
+
+## Problem Statement
+Admins cannot effectively work with Settings Catalog policies when they only see:
+- `settingDefinitionId` strings (e.g., `device_vendor_msft_passportforwork_biometrics_usebiometrics`)
+- Raw JSON structures
+- Choice values as GUIDs or internal strings
+
+This makes policy review, audit, and troubleshooting extremely difficult.
+
+## Goals
+- **Primary**: Render Settings Catalog policies with display names, descriptions, grouped settings, and formatted values
+- **Secondary**: Keep raw JSON available for audit/restore workflows
+- **Tertiary**: Gracefully degrade when definition metadata is unavailable
+
+## User Stories
+
+### P1: US-UI-04 - Admin Views Readable Settings
+**As an** Intune admin  
+**I want to** see policy settings with human-readable names and descriptions  
+**So that** I can understand what the policy configures without reading raw JSON
+
+**Acceptance Criteria:**
+- Display name shown for each setting (not definition ID)
+- Description/help text visible on hover or expand
+- Values formatted appropriately (True/False, numbers, choice labels)
+- Settings grouped by category/section
+
+### P2: US-UI-05 - Admin Searches/Filters Settings
+**As an** Intune admin  
+**I want to** search and filter settings by name or value  
+**So that** I can quickly find specific configurations in large policies
+
+**Acceptance Criteria:**
+- Search box filters settings list
+- Search works on display name and value
+- Results update instantly
+- Clear search resets view
+
+### P3: US-UI-06 - Admin Accesses Raw JSON When Needed
+**As an** Intune admin or auditor  
+**I want to** switch to raw JSON view  
+**So that** I can see the exact Graph API payload for audit/restore
+
+**Acceptance Criteria:**
+- Tab navigation between "Settings" and "JSON" views
+- JSON view shows complete policy snapshot
+- JSON view includes copy-to-clipboard
+- Settings view is default
+
+## Functional Requirements
+
+### FR-185.1: Setting Definition Resolver Service
+- **Input**: Array of `settingDefinitionId` (including children from group settings)
+- **Output**: Map of `{definitionId => {displayName, description, helpText, categoryId, uxBehavior, ...}}`
+- **Strategy**:
+  - Fetch from Graph API settingDefinitions endpoints
+  - Cache in database (`settings_catalog_definitions` table)
+  - Memory cache for request-level performance
+  - Fallback to prettified ID if definition not found
+
+### FR-185.2: Database Schema for Definition Cache
+**Table**: `settings_catalog_definitions`
+- `id` (bigint, PK)
+- `definition_id` (string, unique, indexed)
+- `display_name` (string)
+- `description` (text, nullable)
+- `help_text` (text, nullable)
+- `category_id` (string, nullable)
+- `ux_behavior` (string, nullable)
+- `raw` (jsonb) - full Graph response
+- `timestamps`
+
+### FR-185.3: Snapshot Enrichment (Non-Blocking)
+- After hydrating `/configurationPolicies/{id}/settings`
+- Extract all `settingDefinitionId` + children
+- Call resolver to warm cache
+- Store render hints in snapshot metadata: `definitions_cached: true/false`, `definition_count: N`
+
+### FR-185.4: PolicyNormalizer Enhancement
+- For `settingsCatalogPolicy` type:
+  - Output: `settings_groups[]` = `{title, description?, rows[]}`
+  - Each row: `{label, helpText?, value_display, value_raw, definition_id, instance_type}`
+  - Value formatting:
+    - `integer/bool`: show compact (True/False, numbers)
+    - `choice`: show friendly choice label (extract from `@odata.type` or value tail)
+    - `string`: truncate long values, add copy button
+  - Fallback: prettify `definitionId` if definition not found (e.g., `device_vendor_msft_policy_name` → "Device Vendor Msft Policy Name")
+
+### FR-185.5: Policy View UI Update
+- **Layout**: 2-column
+  - Left: "Configuration Settings" (grouped, searchable)
+  - Right: "Policy Details" (existing metadata: name, type, platform, last synced)
+- **Tabs**:
+  - "Settings" (default) - cleartext UI with accordion groups
+  - "JSON" - raw snapshot viewer (pepperfm/filament-json)
+- **Search/Filter**: Live search on setting display name and value
+- **Accordion**: Settings grouped by category, collapsible
+- **Fallback**: Generic table for non-Settings Catalog policies (existing behavior)
+
+### FR-185.6: JSON Viewer Integration
+- Use `pepperfm/filament-json` only on Policy View and Policy Version View
+- Not rendered globally
+
+## Non-Functional Requirements
+
+### NFR-185.1: Performance
+- Definition resolver: <500ms for batch of 50 definitions (cached)
+- UI render: <2s for policy with 200 settings
+- Search/filter: <200ms response time
+
+### NFR-185.2: Caching Strategy
+- DB cache: 30 days TTL for definitions
+- Memory cache: Request-level only
+- Cache warming: Background job after policy sync (optional)
+
+### NFR-185.3: Graceful Degradation
+- If definition not found: show prettified ID
+- If Graph API fails: show cached data or fallback
+- If no cache: show raw definition ID with info icon
+
+### NFR-185.4: Maintainability
+- Resolver service isolated, testable
+- Normalizer logic separated from UI
+- UI components reusable for Version view
+
+## Technical Architecture
+
+### Services
+1. **SettingsCatalogDefinitionResolver** (`app/Services/Intune/`)
+   - `resolve(array $definitionIds): array`
+   - `resolveOne(string $definitionId): ?array`
+   - `warmCache(array $definitionIds): void`
+   - Uses GraphClientInterface
+   - Database: `SettingsCatalogDefinition` model
+
+2. **PolicyNormalizer** (extend existing)
+   - `normalizeSettingsCatalog(array $snapshot, array $definitions): array`
+   - Returns structured groups + rows
+
+### Database
+**Migration**: `create_settings_catalog_definitions_table`
+**Model**: `SettingsCatalogDefinition` (Eloquent)
+
+### UI Components
+**Resource**: `PolicyResource` (extend infolist)
+- Tabs component
+- Accordion for groups
+- Search/filter component
+- ViewEntry for settings table
+
+## Implementation Plan
+
+### Phase 1: Foundation (Resolver + DB)
+1. Create migration `settings_catalog_definitions`
+2. Create model `SettingsCatalogDefinition`
+3. Create service `SettingsCatalogDefinitionResolver`
+4. Add Graph client method for fetching definitions
+5. Implement cache logic (DB + memory)
+
+### Phase 2: Snapshot Enrichment
+1. Extend `PolicySnapshotService` to extract definition IDs
+2. Call resolver after settings hydration
+3. Store metadata in snapshot
+
+### Phase 3: Normalizer Enhancement
+1. Extend `PolicyNormalizer` for Settings Catalog
+2. Implement value formatting logic
+3. Implement grouping logic
+4. Add fallback for missing definitions
+
+### Phase 4: UI Implementation
+1. Update `PolicyResource` infolist with tabs
+2. Create accordion view for settings groups
+3. Add search/filter functionality
+4. Integrate JSON viewer (pepperfm)
+5. Add fallback for non-Settings Catalog policies
+
+### Phase 5: Testing & Polish
+1. Unit tests for resolver
+2. Feature tests for UI
+3. Manual QA on staging
+4. Performance profiling
+
+## Testing Strategy
+
+### Unit Tests
+- `SettingsCatalogDefinitionResolverTest`
+  - Test definition mapping
+  - Test caching behavior
+  - Test fallback logic
+  - Test batch resolution
+
+### Feature Tests
+- `PolicyViewSettingsCatalogReadableTest`
+  - Mock Graph responses
+  - Assert UI shows display names
+  - Assert values formatted correctly
+  - Assert grouping works
+  - Assert search/filter works
+  - Assert JSON tab available
+
+## Success Criteria
+
+1. ✅ Admin sees human-readable setting names + descriptions
+2. ✅ Values formatted appropriately (True/False, numbers, choice labels)
+3. ✅ Settings grouped by category with accordion
+4. ✅ Search/filter works on display name and value
+5. ✅ Raw JSON available in separate tab
+6. ✅ Unknown settings show prettified ID (no broken layout)
+7. ✅ Performance: <2s render for 200 settings
+8. ✅ Tests pass: Unit + Feature
+
+## Dependencies
+- Existing: `PolicyNormalizer`, `PolicySnapshotService`, `GraphClientInterface`
+- New: `pepperfm/filament-json` (already installed in Feature 002)
+- Database: PostgreSQL with JSONB support
+
+## Risks & Mitigations
+- **Risk**: Graph API rate limiting when fetching definitions
+  - **Mitigation**: Aggressive caching, batch requests, background warming
+- **Risk**: Definition schema changes by Microsoft
+  - **Mitigation**: Raw JSONB storage allows flexible parsing, version metadata
+- **Risk**: Large policies (1000+ settings) slow UI
+  - **Mitigation**: Pagination, lazy loading accordion groups, virtualized lists
+
+## Out of Scope
+- Editing settings (read-only view only)
+- Definition schema versioning
+- Multi-language support for definitions
+- Real-time definition updates (cache refresh manual/scheduled)
+
+## Future Enhancements
+- Background job to pre-warm definition cache
+- Definition schema versioning
+- Comparison view between policy versions (diff)
+- Export settings to CSV/Excel

specs/185-settings-catalog-readable/tasks.md

@@ -0,0 +1,472 @@
+# Feature 185: Settings Catalog Readable UI - Tasks
+
+## Summary
+- **Total Tasks**: 42
+- **User Stories**: 3 (US-UI-04, US-UI-05, US-UI-06)
+- **Estimated Time**: 11-15 hours
+- **Phases**: 7
+
+## FR→Task Traceability
+
+| FR | Description | Tasks |
+|----|-------------|-------|
+| FR-185.1 | Setting Definition Resolver Service | T003, T004, T005, T006, T007 |
+| FR-185.2 | Database Schema | T001, T002 |
+| FR-185.3 | Snapshot Enrichment | T008, T009, T010 |
+| FR-185.4 | PolicyNormalizer Enhancement | T011, T012, T013, T014 |
+| FR-185.5 | Policy View UI Update | T015-T024 |
+| FR-185.6 | JSON Viewer Integration | T025 |
+
+## User Story→Task Mapping
+
+| User Story | Tasks | Success Criteria |
+|------------|-------|------------------|
+| US-UI-04 (Readable Settings) | T015-T020 | Display names shown, values formatted, grouped by category |
+| US-UI-05 (Search/Filter) | T021, T022 | Search box works, filters settings, instant results |
+| US-UI-06 (Raw JSON Access) | T023, T024, T025 | Tabs present, JSON view works, copy button functional |
+
+## Measurable Thresholds
+- **Definition Resolution**: <500ms for batch of 50 definitions (cached)
+- **UI Render**: <2s for policy with 200 settings
+- **Search Response**: <200ms filter update
+- **Database Cache TTL**: 30 days
+
+---
+
+## Phase 1: Database Foundation (T001-T002)
+
+**Goal**: Create database schema for caching setting definitions
+
+- [X] **T001** Create migration for `settings_catalog_definitions` table
+  - Schema: id, definition_id (unique), display_name, description, help_text, category_id, ux_behavior, raw (jsonb), timestamps
+  - Indexes: definition_id (unique), category_id, raw (GIN)
+  - File: `database/migrations/2025_12_13_212126_create_settings_catalog_definitions_table.php`
+  - **Implementation Note**: Created migration with GIN index for JSONB, ran successfully
+
+- [X] **T002** Create `SettingsCatalogDefinition` Eloquent model
+  - Casts: raw → array
+  - Fillable: definition_id, display_name, description, help_text, category_id, ux_behavior, raw
+  - File: `app/Models/SettingsCatalogDefinition.php`
+  - **Implementation Note**: Added helper methods findByDefinitionId() and findByDefinitionIds() for efficient lookups
+
+---
+
+## Phase 2: Definition Resolver Service (T003-T007)
+
+**Goal**: Implement service to fetch and cache setting definitions from Graph API
+
+**User Story**: US-UI-04 (foundation)
+
+- [X] **T003** [P] Create `SettingsCatalogDefinitionResolver` service skeleton
+  - Constructor: inject GraphClientInterface, SettingsCatalogDefinition model
+  - Methods: resolve(), resolveOne(), warmCache(), clearCache()
+  - File: `app/Services/Intune/SettingsCatalogDefinitionResolver.php`
+  - **Implementation Note**: Complete service with 3-tier caching (memory → DB → Graph API)
+
+- [X] **T004** [P] [US1] Implement `resolve(array $definitionIds): array` method
+  - Check memory cache (Laravel Cache)
+  - Check database cache
+  - Batch fetch missing from Graph API: `/deviceManagement/configurationSettings?$filter=id in (...)`
+  - Store in DB + memory cache
+  - Return map: `{definitionId => {displayName, description, ...}}`
+  - File: `app/Services/Intune/SettingsCatalogDefinitionResolver.php`
+  - **Implementation Note**: Implemented with batch request optimization and error handling
+
+- [X] **T005** [P] [US1] Implement `resolveOne(string $definitionId): ?array` method
+  - Single definition lookup
+  - Same caching strategy as resolve()
+  - Return null if not found
+  - File: `app/Services/Intune/SettingsCatalogDefinitionResolver.php`
+  - **Implementation Note**: Wraps resolve() for single ID lookup
+
+- [X] **T006** [US1] Implement fallback logic for missing definitions
+  - Prettify definition ID: `device_vendor_msft_policy_name` → "Device Vendor Msft Policy Name"
+  - Return fallback structure: `{displayName: prettified, description: null, ...}`
+  - File: `app/Services/Intune/SettingsCatalogDefinitionResolver.php`
+  - **Implementation Note**: prettifyDefinitionId() method with Str::title() conversion, isFallback flag added
+
+- [X] **T007** [P] Implement `warmCache(array $definitionIds): void` method
+  - Pre-populate cache without returning data
+  - Non-blocking: catch and log Graph API errors
+  - File: `app/Services/Intune/SettingsCatalogDefinitionResolver.php`
+  - **Implementation Note**: Non-blocking implementation with try/catch, logs warnings on failure
+
+---
+
+## Phase 3: Snapshot Enrichment (T008-T010)
+
+**Goal**: Extend PolicySnapshotService to warm definition cache after settings hydration
+
+**User Story**: US-UI-04 (foundation)
+
+- [X] **T008** [US1] Extend `PolicySnapshotService` to extract definition IDs
+  - After hydrating `/configurationPolicies/{id}/settings`
+  - Extract all `settingDefinitionId` from settings array
+  - Include children from `groupSettingCollectionInstance`
+  - File: `app/Services/Intune/PolicySnapshotService.php`
+  - **Implementation Note**: Added extractDefinitionIds() method with recursive extraction from nested children
+
+- [X] **T009** [US1] Call SettingsCatalogDefinitionResolver::warmCache() in snapshot flow
+  - Pass extracted definition IDs to resolver
+  - Non-blocking: use try/catch for Graph API calls
+  - File: `app/Services/Intune/PolicySnapshotService.php`
+  - **Implementation Note**: Integrated warmCache() call in hydrateSettingsCatalog() after settings extraction
+
+- [X] **T010** [US1] Add metadata to snapshot about definition cache status
+  - Add to snapshot: `definitions_cached: true/false`, `definition_count: N`
+  - Store with snapshot data
+  - File: `app/Services/Intune/PolicySnapshotService.php`
+  - **Implementation Note**: Added definitions_cached and definition_count to metadata
+
+---
+
+## Phase 4: PolicyNormalizer Enhancement (T011-T014)
+
+**Goal**: Transform Settings Catalog snapshots into UI-ready grouped structure
+
+**User Story**: US-UI-04
+
+- [X] **T011** [US1] Create `normalizeSettingsCatalogGrouped()` method in PolicyNormalizer
+  - Input: array $snapshot, array $definitions
+  - Output: array with groups[] structure
+  - Extract settings from snapshot
+  - Resolve definitions for all setting IDs
+  - File: `app/Services/Intune/PolicyNormalizer.php`
+  - **Implementation Note**: Complete method with definition resolution integration
+
+- [X] **T012** [US1] Implement value formatting logic
+  - ChoiceSettingInstance: Extract choice label from @odata.type or value
+  - SimpleSetting (bool): "Enabled" / "Disabled"
+  - SimpleSetting (int): Number formatted with separators
+  - SimpleSetting (string): Truncate >100 chars, add "..."
+  - File: `app/Services/Intune/PolicyNormalizer.php`
+  - **Implementation Note**: Added formatSettingsCatalogValue() method with all formatting rules
+
+- [X] **T013** [US1] Implement grouping logic by category
+  - Group settings by categoryId from definition metadata
+  - Fallback: Group by first segment of definition ID
+  - Sort groups alphabetically by title
+  - File: `app/Services/Intune/PolicyNormalizer.php`
+  - **Implementation Note**: Added groupSettingsByCategory() with fallback extraction from definition IDs
+
+- [X] **T014** [US1] Implement nested group flattening for groupSettingCollectionInstance
+  - Recursively extract children from group settings
+  - Maintain hierarchy in output structure
+  - Include parent context in child labels
+  - File: `app/Services/Intune/PolicyNormalizer.php`
+  - **Implementation Note**: Recursive walk function handles nested children and group collections
+
+---
+
+## Phase 5: UI Implementation - Settings Tab (T015-T022)
+
+**Goal**: Create readable Settings Catalog UI with accordion, search, and formatting
+
+**User Stories**: US-UI-04, US-UI-05
+
+- [X] **T015** [US1] Add Tabs component to PolicyResource infolist for settingsCatalogPolicy
+  - Conditional rendering: only for settingsCatalogPolicy type
+  - Tab 1: "Settings" (default)
+  - Tab 2: "JSON" (existing from Feature 002)
+  - File: `app/Filament/Resources/PolicyResource.php`
+  - **Implementation Note**: Tabs already exist from Feature 002, extended Settings tab with grouped view
+
+- [X] **T016** [US1] Create Settings tab schema with search input
+  - TextInput for search/filter at top
+  - Placeholder: "Search settings..."
+  - Wire with Livewire for live filtering
+  - File: `app/Filament/Resources/PolicyResource.php`
+  - **Implementation Note**: Added search_info TextEntry (hidden for MVP), search implemented in Blade template
+
+- [X] **T017** [US1] Create Blade component for grouped settings accordion
+  - File: `resources/views/filament/infolists/entries/settings-catalog-grouped.blade.php`
+  - Props: groups (from normalizer), searchQuery
+  - Render accordion with Filament Section components
+  - **Implementation Note**: Complete Blade component with Filament Section integration
+
+- [X] **T018** [US1] Implement accordion group rendering
+  - Each group: Section with title + description
+  - Collapsible by default (first group expanded)
+  - Group header shows setting count
+  - File: `settings-catalog-grouped.blade.php`
+  - **Implementation Note**: Using x-filament::section with collapsible, first group expanded by default
+
+- [X] **T019** [US1] Implement setting row rendering within groups
+  - Layout: Label (bold) | Value (formatted) | Help icon
+  - Help icon: Tooltip with description + helpText
+  - Copy button for long values
+  - File: `settings-catalog-grouped.blade.php`
+  - **Implementation Note**: Flexbox layout with label, help text, value display, and Alpine.js copy button
+
+- [X] **T020** [US1] Add value formatting in Blade template
+  - Bool: Badge (Enabled/Disabled with colors)
+  - Int: Formatted number
+  - String: Truncate with "..." and expand button
+  - Choice: Show choice label
+  - File: `settings-catalog-grouped.blade.php`
+  - **Implementation Note**: Conditional rendering based on value type, badges for bool, monospace for int
+
+- [X] **T021** [US2] Implement search/filter logic in Livewire component
+  - Filter groups and settings by search query
+  - Search on display_name and value_display
+  - Update accordion to show only matching settings
+  - File: `app/Filament/Resources/PolicyResource.php` (or custom Livewire component)
+  - **Implementation Note**: Blade-level filtering using searchQuery prop, no Livewire component needed for MVP
+
+- [X] **T022** [US2] Add "No results" empty state for search
+  - Show message when search returns no matches
+  - Provide "Clear search" button
+  - File: `settings-catalog-grouped.blade.php`
+  - **Implementation Note**: Empty state with clear search button using wire:click
+
+---
+
+## Phase 6: UI Implementation - Tabs & Fallback (T023-T025)
+
+**Goal**: Complete tab navigation and handle non-Settings Catalog policies
+
+**User Story**: US-UI-06
+
+- [ ] **T023** [US3] Verify JSON tab still works (from Feature 002)
+  - Tab navigation switches correctly
+  - JSON viewer renders snapshot
+  - Copy button functional
+  - File: `app/Filament/Resources/PolicyResource.php`
+
+- [ ] **T024** [US3] Add fallback for policies without cached definitions
+  - Show info message in Settings tab: "Definitions not cached. Showing raw data."
+  - Display raw definition IDs with prettified labels
+  - Link to "View JSON" tab
+  - File: `settings-catalog-grouped.blade.php`
+
+- [ ] **T025** Ensure JSON viewer only renders on Policy View (not globally)
+  - Check existing implementation from Feature 002
+  - Verify pepperfm/filament-json scoped correctly
+  - File: `app/Filament/Resources/PolicyResource.php`
+
+---
+
+## Phase 7: Testing & Validation (T026-T042)
+
+**Goal**: Comprehensive testing for resolver, normalizer, and UI
+
+### Unit Tests (T026-T031)
+
+- [ ] **T026** [P] Create `SettingsCatalogDefinitionResolverTest` test file
+  - File: `tests/Unit/SettingsCatalogDefinitionResolverTest.php`
+  - Setup: Mock GraphClientInterface, in-memory database
+
+- [ ] **T027** [P] Test `resolve()` method with batch of definition IDs
+  - Assert: Returns map with display names
+  - Assert: Caches in database
+  - Assert: Uses cached data on second call
+  - File: `tests/Unit/SettingsCatalogDefinitionResolverTest.php`
+
+- [ ] **T028** [P] Test fallback logic for missing definitions
+  - Mock: Graph API returns 404
+  - Assert: Returns prettified definition ID
+  - Assert: No exception thrown
+  - File: `tests/Unit/SettingsCatalogDefinitionResolverTest.php`
+
+- [ ] **T029** [P] Create `PolicyNormalizerSettingsCatalogTest` test file
+  - File: `tests/Unit/PolicyNormalizerSettingsCatalogTest.php`
+  - Setup: Mock definition data, sample snapshot
+
+- [ ] **T030** [P] Test grouping logic in normalizer
+  - Input: Snapshot with settings from different categories
+  - Assert: Groups created correctly
+  - Assert: Groups sorted alphabetically
+  - File: `tests/Unit/PolicyNormalizerSettingsCatalogTest.php`
+
+- [ ] **T031** [P] Test value formatting in normalizer
+  - Test bool → "Enabled"/"Disabled"
+  - Test int → formatted number
+  - Test string → truncation
+  - Test choice → label extraction
+  - File: `tests/Unit/PolicyNormalizerSettingsCatalogTest.php`
+
+### Feature Tests (T032-T037)
+
+- [ ] **T032** [P] Create `PolicyViewSettingsCatalogReadableTest` test file
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+  - Setup: Mock GraphClient, create test policy with Settings Catalog type
+
+- [ ] **T033** Test Settings Catalog policy view shows tabs
+  - Navigate to Policy View
+  - Assert: Tabs component present
+  - Assert: "Settings" and "JSON" tabs visible
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+
+- [ ] **T034** Test Settings tab shows display names (not definition IDs)
+  - Mock: Definitions cached
+  - Assert: Display names shown in UI
+  - Assert: Definition IDs NOT visible
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+
+- [ ] **T035** Test values formatted correctly
+  - Mock: Settings with bool, int, string, choice values
+  - Assert: Bool shows "Enabled"/"Disabled"
+  - Assert: Int shows formatted number
+  - Assert: String shows truncated value
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+
+- [ ] **T036** [US2] Test search/filter functionality
+  - Input: Type search query
+  - Assert: Settings list filtered
+  - Assert: Only matching settings shown
+  - Assert: Clear search resets view
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+
+- [ ] **T037** Test graceful degradation for missing definitions
+  - Mock: Definitions not cached
+  - Assert: Fallback labels shown (prettified IDs)
+  - Assert: No broken layout
+  - Assert: Info message visible
+  - File: `tests/Feature/Filament/PolicyViewSettingsCatalogReadableTest.php`
+
+### Validation & Polish (T038-T042)
+
+- [ ] **T038** Run Pest test suite for Feature 185
+  - Command: `./vendor/bin/sail artisan test --filter=SettingsCatalog`
+  - Assert: All tests pass
+  - Fix any failures
+
+- [ ] **T039** Run Laravel Pint on modified files
+  - Command: `./vendor/bin/sail pint --dirty`
+  - Assert: No style issues
+  - Commit fixes
+
+- [ ] **T040** Review git changes for Feature 185
+  - Check: No changes to forbidden areas (see constitution)
+  - Verify: Only expected files modified
+  - Document: List of changed files in research.md
+
+- [ ] **T041** Run database migration on local environment
+  - Command: `./vendor/bin/sail artisan migrate`
+  - Verify: `settings_catalog_definitions` table created
+  - Check: Indexes applied correctly
+
+- [ ] **T042** Manual QA: Policy View with Settings Catalog policy
+  - Navigate to Policy View for Settings Catalog policy
+  - Verify: Tabs present ("Settings" and "JSON")
+  - Verify: Settings tab shows accordion with groups
+  - Verify: Display names shown (not raw IDs)
+  - Verify: Values formatted correctly
+  - Test: Search filters settings
+  - Test: JSON tab works
+  - Test: Copy buttons functional
+  - Test: Dark mode toggle
+
+---
+
+## Dependencies & Execution Order
+
+### Sequential Dependencies
+- **Phase 1** → **Phase 2**: Database must exist before resolver can cache
+- **Phase 2** → **Phase 3**: Resolver must exist before snapshot enrichment
+- **Phase 2** → **Phase 4**: Definitions needed for normalizer
+- **Phase 4** → **Phase 5**: Normalized data structure needed for UI
+- **Phase 5** → **Phase 7**: UI must exist before feature tests
+
+### Parallel Opportunities
+- **Phase 2** (T003-T007): Resolver methods can be implemented in parallel
+- **Phase 4** (T011-T014): Normalizer sub-methods can be implemented in parallel
+- **Phase 5** (T015-T022): UI components can be developed in parallel after T015
+- **Phase 7** (T026-T031): Unit tests can be written in parallel
+- **Phase 7** (T032-T037): Feature tests can be written in parallel
+
+### Example Parallel Execution
+**Phase 2**:
+- Developer A: T003, T004 (resolve methods)
+- Developer B: T005, T006 (resolveOne + fallback)
+- Both converge for T007 (warmCache)
+
+**Phase 5**:
+- Developer A: T015-T017 (tabs + accordion setup)
+- Developer B: T018-T020 (rendering logic)
+- Both converge for T021-T022 (search functionality)
+
+---
+
+## Task Complexity Estimates
+
+| Phase | Task Count | Estimated Time | Dependencies |
+|-------|------------|----------------|--------------|
+| Phase 1: Database | 2 | ~30 min | None |
+| Phase 2: Resolver | 5 | ~2-3 hours | Phase 1 |
+| Phase 3: Snapshot | 3 | ~1 hour | Phase 2 |
+| Phase 4: Normalizer | 4 | ~2-3 hours | Phase 2 |
+| Phase 5: UI Settings | 8 | ~3-4 hours | Phase 4 |
+| Phase 6: UI Tabs | 3 | ~1 hour | Phase 5 |
+| Phase 7: Testing | 17 | ~3-4 hours | Phase 2-6 |
+| **Total** | **42** | **11-15 hours** | |
+
+---
+
+## Success Criteria Checklist
+
+- [X] **SC-001**: Admin sees human-readable setting names (not definition IDs) on Policy View (Implementation complete - requires manual verification)
+- [X] **SC-002**: Setting values formatted appropriately (True/False, numbers, choice labels) (Implementation complete - requires manual verification)
+- [X] **SC-003**: Settings grouped by category with accordion (collapsible sections) (Implementation complete - requires manual verification)
+- [X] **SC-004**: Search/filter works on display name and value (<200ms response) (Blade-level implementation complete - requires manual verification)
+- [X] **SC-005**: Raw JSON available in separate "JSON" tab (Feature 002 integration preserved)
+- [X] **SC-006**: Unknown settings show prettified ID fallback (no broken layout) (Implementation complete - requires manual verification)
+- [ ] **SC-007**: Performance: <2s render for policy with 200 settings (Requires load testing)
+- [ ] **SC-008**: Tests pass: Unit tests for resolver + normalizer (Tests not written yet)
+- [ ] **SC-009**: Tests pass: Feature tests for UI rendering (Tests not written yet)
+- [ ] **SC-010**: Definition resolution: <500ms for batch of 50 (cached) (Requires benchmark testing)
+
+---
+
+## Constitution Compliance Evidence
+
+| Principle | Evidence | Tasks |
+|-----------|----------|-------|
+| Safety-First | Read-only UI, no edit capabilities | All UI tasks |
+| Immutable Versioning | Snapshot enrichment non-blocking, metadata only | T008-T010 |
+| Defensive Restore | Not applicable (read-only feature) | N/A |
+| Auditability | Raw JSON still accessible via tab | T023-T025 |
+| Tenant-Aware | Resolver respects tenant scoping (via GraphClient) | T003-T007 |
+| Graph Abstraction | Uses existing GraphClientInterface | T003-T007 |
+| Spec-Driven | Full spec + plan + tasks before implementation | This document |
+
+---
+
+## Risk Mitigation Tasks
+
+- **Risk**: Graph API rate limiting
+  - **Mitigation**: T007 (warmCache is non-blocking), aggressive DB caching
+- **Risk**: Definition schema changes by Microsoft
+  - **Mitigation**: T001 (raw JSONB storage), T006 (fallback logic)
+- **Risk**: Large policies slow UI
+  - **Mitigation**: T017-T018 (accordion lazy-loading), performance tests in T042
+
+---
+
+## Notes for Implementation
+
+1. **Feature 002 Dependency**: Feature 185 uses tabs from Feature 002 JSON viewer implementation. Ensure Feature 002 code is stable before starting Phase 5.
+
+2. **Database Migration**: Run migration early (T001) to avoid blocking later phases.
+
+3. **Graph API Endpoints**: Verify access to `/deviceManagement/configurationSettings` endpoint in test environment before implementing T004.
+
+4. **Testing Strategy**: Write unit tests (Phase 7, T026-T031) in parallel with implementation to enable TDD workflow.
+
+5. **UI Polish**: Leave time for manual QA (T042) to catch UX issues not covered by automated tests.
+
+6. **Performance Profiling**: Use Laravel Telescope or Debugbar during T042 to measure actual performance vs NFR targets.
+
+---
+
+## Implementation Readiness
+
+**Prerequisites**:
+- ✅ Feature 002 JSON viewer implemented (tabs pattern established)
+- ✅ pepperfm/filament-json installed
+- ✅ GraphClientInterface available
+- ✅ PolicyNormalizer exists
+- ✅ PolicySnapshotService exists
+- ✅ PostgreSQL with JSONB support
+
+**Ready to Start**: Phase 1 (Database Foundation)

tests/Feature/Filament/BackupCreationTest.php

@@ -34,6 +34,11 @@ public function applyPolicy(string $policyType, string $policyId, array $payload
             return new GraphResponse(true, []);
         }
 
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
         public function request(string $method, string $path, array $options = []): GraphResponse
         {
             return new GraphResponse(true, []);

tests/Feature/Filament/ODataTypeMismatchTest.php

@@ -42,6 +42,11 @@ public function request(string $method, string $path, array $options = []): Grap
         {
             return new GraphResponse(true, []);
         }
+
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
     });
 
     $tenant = Tenant::create([
@@ -62,7 +67,7 @@ public function request(string $method, string $path, array $options = []): Grap
     ]);
 
     $snapshot = [
-        '@odata.type' => '#microsoft.graph.iosGeneralDeviceConfiguration',
+        '@odata.type' => '#microsoft.graph.unknownConfiguration',
         'displayName' => 'Policy A',
     ];
 

tests/Feature/Filament/PolicyVersionReadableLayoutTest.php

@@ -0,0 +1,80 @@
+<?php
+
+use App\Filament\Resources\PolicyVersionResource;
+use App\Models\Policy;
+use App\Models\PolicyVersion;
+use App\Models\Tenant;
+use App\Models\User;
+use Carbon\CarbonImmutable;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+test('policy version detail renders tabs and scroll-safe blocks', function () {
+    $tenant = Tenant::create([
+        'tenant_id' => env('INTUNE_TENANT_ID', 'local-tenant'),
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $tenant->makeCurrent();
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-policy-1',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Policy',
+        'platform' => 'windows',
+    ]);
+
+    $longDefinitionId = 'device_vendor_msft_policy_config_system_'.str_repeat('minimumpinlength_', 12);
+
+    $version = PolicyVersion::create([
+        'tenant_id' => $tenant->id,
+        'policy_id' => $policy->id,
+        'version_number' => 1,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'created_by' => 'tester@example.com',
+        'captured_at' => CarbonImmutable::now(),
+        'snapshot' => [
+            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+            'displayName' => $policy->display_name,
+            'settings' => [
+                [
+                    'id' => 's1',
+                    'settingInstance' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                        'settingDefinitionId' => $longDefinitionId,
+                        'simpleSettingValue' => [
+                            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationIntegerSettingValue',
+                            'value' => 12,
+                        ],
+                    ],
+                ],
+            ],
+        ],
+    ]);
+
+    $user = User::factory()->create();
+
+    $response = $this->actingAs($user)
+        ->get(PolicyVersionResource::getUrl('view', ['record' => $version]));
+
+    $response->assertOk();
+    $response->assertSee('Normalized settings');
+    $response->assertSee('Raw JSON');
+    $response->assertSee('Diff');
+
+    $response->assertSee('max-h-[520px]');
+    $response->assertSee('overflow-auto');
+    $response->assertSee('font-mono');
+
+    $response->assertSee('Definition');
+    $response->assertSee('Type');
+    $response->assertSee('Value');
+    $response->assertSee('fi-ta-table');
+    $response->assertSee('Details');
+});

tests/Feature/Filament/RestoreExecutionTest.php

@@ -40,6 +40,11 @@ public function request(string $method, string $path, array $options = []): Grap
         {
             return new GraphResponse(true, []);
         }
+
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
     });
 
     $tenant = Tenant::create([

tests/Feature/Filament/RestorePreviewTest.php

@@ -34,6 +34,11 @@ public function applyPolicy(string $policyType, string $policyId, array $payload
             return new GraphResponse(true, []);
         }
 
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
         public function request(string $method, string $path, array $options = []): GraphResponse
         {
             return new GraphResponse(true, []);

tests/Feature/Filament/SettingsCatalogPolicyHydrationTest.php

@@ -0,0 +1,156 @@
+<?php
+
+use App\Models\Policy;
+use App\Models\Tenant;
+use App\Models\User;
+use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphResponse;
+use App\Services\Intune\BackupService;
+use App\Services\Intune\VersionService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+class SettingsCatalogHydrationGraphClient implements GraphClientInterface
+{
+    public array $requests = [];
+
+    public function listPolicies(string $policyType, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse
+    {
+        $this->requests[] = ['getPolicy', $policyType, $policyId];
+
+        return new GraphResponse(true, ['payload' => [
+            'id' => $policyId,
+            'displayName' => 'Settings Catalog Alpha',
+            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+        ]]);
+    }
+
+    public function getOrganization(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function applyPolicy(string $policyType, string $policyId, array $payload, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function getServicePrincipalPermissions(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function request(string $method, string $path, array $options = []): GraphResponse
+    {
+        $this->requests[] = [$method, $path];
+
+        if (str_contains($path, '/settings')) {
+            return new GraphResponse(true, [
+                'value' => [
+                    ['displayName' => 'Setting A', 'value' => 'on'],
+                    ['displayName' => 'Setting B', 'value' => 'off'],
+                ],
+            ]);
+        }
+
+        return new GraphResponse(true, []);
+    }
+}
+
+test('settings catalog snapshot hydrates configuration settings and renders in policy detail', function () {
+    $client = new SettingsCatalogHydrationGraphClient;
+    app()->instance(GraphClientInterface::class, $client);
+
+    $tenant = Tenant::create([
+        'tenant_id' => 'tenant-hydration',
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $_ENV['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+    $_SERVER['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+    $tenant->makeCurrent();
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-hydrate',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Alpha',
+        'platform' => 'windows',
+    ]);
+
+    /** @var BackupService $backupService */
+    $backupService = app(BackupService::class);
+    $backupSet = $backupService->createBackupSet($tenant, [$policy->id], actorEmail: 'tester@example.com');
+
+    $item = $backupSet->items()->first();
+    expect($item->payload)->toHaveKey('settings');
+    expect(count($item->payload['settings']))->toBe(2);
+
+    /** @var VersionService $versions */
+    $versions = app(VersionService::class);
+    $versions->captureVersion(
+        policy: $policy,
+        payload: $item->payload,
+        createdBy: 'tester@example.com',
+        metadata: ['source' => 'test', 'backup_set_id' => $backupSet->id],
+    );
+
+    $user = User::factory()->create();
+
+    $response = $this
+        ->actingAs($user)
+        ->get(route('filament.admin.resources.policies.view', ['record' => $policy]));
+
+    $response->assertOk();
+    $response->assertSee('Setting A');
+    $response->assertSee('on');
+    $response->assertSee('Settings');
+});
+
+test('settings catalog version capture hydrates settings from graph', function () {
+    $client = new SettingsCatalogHydrationGraphClient;
+    app()->instance(GraphClientInterface::class, $client);
+
+    $tenant = Tenant::create([
+        'tenant_id' => 'tenant-hydration-version',
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $_ENV['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+    $_SERVER['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+    $tenant->makeCurrent();
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-version',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Beta',
+        'platform' => 'windows',
+    ]);
+
+    /** @var VersionService $versions */
+    $versions = app(VersionService::class);
+    $versions->captureFromGraph($tenant, $policy, createdBy: 'tester@example.com');
+
+    $user = User::factory()->create();
+
+    $response = $this
+        ->actingAs($user)
+        ->get(route('filament.admin.resources.policies.view', ['record' => $policy]));
+
+    $response->assertOk();
+    $response->assertSee('Setting A');
+    $response->assertSee('Setting B');
+});

tests/Feature/Filament/SettingsCatalogPolicyNormalizedDisplayTest.php

@@ -0,0 +1,110 @@
+<?php
+
+use App\Filament\Resources\PolicyResource;
+use App\Filament\Resources\PolicyVersionResource;
+use App\Models\Policy;
+use App\Models\PolicyVersion;
+use App\Models\Tenant;
+use App\Models\User;
+use Carbon\CarbonImmutable;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+test('settings catalog policies render a normalized settings table', function () {
+    $tenant = Tenant::create([
+        'tenant_id' => env('INTUNE_TENANT_ID', 'local-tenant'),
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $tenant->makeCurrent();
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-policy-1',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Policy',
+        'platform' => 'windows',
+    ]);
+
+    $version = PolicyVersion::create([
+        'tenant_id' => $tenant->id,
+        'policy_id' => $policy->id,
+        'version_number' => 1,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'created_by' => 'tester@example.com',
+        'captured_at' => CarbonImmutable::now(),
+        'snapshot' => [
+            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+            'settings' => [
+                [
+                    'id' => 's1',
+                    'settingInstance' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                        'settingDefinitionId' => 'device_vendor_msft_policy_config_system_minimumpinlength',
+                        'simpleSettingValue' => [
+                            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationIntegerSettingValue',
+                            'value' => 12,
+                        ],
+                    ],
+                ],
+                [
+                    'id' => 's2',
+                    'settingInstance' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance',
+                        'settingDefinitionId' => 'device_vendor_msft_policy_config_system_usebiometrics',
+                        'choiceSettingValue' => [
+                            'value' => 'device_vendor_msft_policy_config_system_usebiometrics_true',
+                        ],
+                    ],
+                ],
+                [
+                    'id' => 'group',
+                    'settingInstance' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationGroupSettingCollectionInstance',
+                        'settingDefinitionId' => 'device_vendor_msft_policy_config_system_group',
+                        'groupSettingCollectionValue' => [
+                            [
+                                'children' => [
+                                    [
+                                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                                        'settingDefinitionId' => 'device_vendor_msft_policy_config_system_child',
+                                        'simpleSettingValue' => [
+                                            'value' => true,
+                                        ],
+                                    ],
+                                ],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ],
+    ]);
+
+    $user = User::factory()->create();
+
+    $policyResponse = $this->actingAs($user)
+        ->get(PolicyResource::getUrl('view', ['record' => $policy]));
+
+    $policyResponse->assertOk();
+    $policyResponse->assertSee('Definition');
+    $policyResponse->assertSee('Type');
+    $policyResponse->assertSee('Value');
+    $policyResponse->assertSee('device_vendor_msft_policy_config_system_minimumpinlength');
+    $policyResponse->assertSee('12');
+    $policyResponse->assertSee('SimpleSettingInstance');
+
+    $versionResponse = $this->actingAs($user)
+        ->get(PolicyVersionResource::getUrl('view', ['record' => $version]));
+
+    $versionResponse->assertOk();
+    $versionResponse->assertSee('Normalized settings');
+    $versionResponse->assertSee('device_vendor_msft_policy_config_system_usebiometrics');
+    $versionResponse->assertSee('usebiometrics_true');
+    $versionResponse->assertSee('device_vendor_msft_policy_config_system_child');
+});

tests/Feature/Filament/SettingsCatalogPolicySyncTest.php

@@ -0,0 +1,128 @@
+<?php
+
+use App\Models\Policy;
+use App\Models\PolicyVersion;
+use App\Models\Tenant;
+use App\Models\User;
+use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphResponse;
+use App\Services\Intune\PolicySyncService;
+use Carbon\CarbonImmutable;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+class SettingsCatalogFakeGraphClient implements GraphClientInterface
+{
+    /**
+     * @param  array<string, GraphResponse>  $responses
+     */
+    public function __construct(private array $responses = []) {}
+
+    public function listPolicies(string $policyType, array $options = []): GraphResponse
+    {
+        return $this->responses[$policyType] ?? new GraphResponse(true, []);
+    }
+
+    public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function getOrganization(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function applyPolicy(string $policyType, string $policyId, array $payload, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function getServicePrincipalPermissions(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function request(string $method, string $path, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+}
+
+test('settings catalog policies sync as their own type and render in the list', function () {
+    $responses = [
+        'deviceConfiguration' => new GraphResponse(true, [
+            [
+                'id' => 'config-1',
+                'displayName' => 'Device Config 1',
+                'platform' => 'windows',
+            ],
+        ]),
+        'settingsCatalogPolicy' => new GraphResponse(true, [
+            [
+                'id' => 'scp-1',
+                'name' => 'Settings Catalog Alpha',
+                'platform' => 'windows',
+                '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+                'settings' => [
+                    ['displayName' => 'Setting A', 'value' => 'on'],
+                ],
+            ],
+        ]),
+    ];
+
+    app()->instance(GraphClientInterface::class, new SettingsCatalogFakeGraphClient($responses));
+
+    $tenant = Tenant::create([
+        'tenant_id' => env('INTUNE_TENANT_ID', 'local-tenant'),
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $_ENV['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+    $_SERVER['INTUNE_TENANT_ID'] = $tenant->tenant_id;
+
+    $tenant->makeCurrent();
+    expect(Tenant::current()->id)->toBe($tenant->id);
+
+    app(PolicySyncService::class)->syncPolicies($tenant);
+
+    $settingsPolicy = Policy::where('policy_type', 'settingsCatalogPolicy')->first();
+
+    expect($settingsPolicy)->not->toBeNull();
+    expect($settingsPolicy->display_name)->toBe('Settings Catalog Alpha');
+    expect($settingsPolicy->platform)->toBe('windows');
+
+    expect(Policy::where('policy_type', 'deviceConfiguration')->count())->toBe(1);
+    expect(Policy::where('policy_type', 'deviceConfiguration')->where('external_id', 'scp-1')->exists())->toBeFalse();
+
+    PolicyVersion::create([
+        'tenant_id' => $tenant->id,
+        'policy_id' => $settingsPolicy->id,
+        'version_number' => 1,
+        'policy_type' => $settingsPolicy->policy_type,
+        'platform' => $settingsPolicy->platform,
+        'created_by' => 'tester@example.com',
+        'captured_at' => CarbonImmutable::now(),
+        'snapshot' => [
+            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+            'settings' => [
+                ['displayName' => 'Setting A', 'value' => 'on'],
+            ],
+        ],
+    ]);
+
+    $user = User::factory()->create();
+
+    $response = $this
+        ->actingAs($user)
+        ->get(route('filament.admin.resources.policies.index'));
+
+    $response->assertOk();
+    $response->assertSee('Settings Catalog Policy');
+    $response->assertSee('Settings Catalog Alpha');
+    $response->assertSee('Available');
+});

tests/Feature/Filament/SettingsCatalogRestoreApplySettingsPatchTest.php

@@ -0,0 +1,174 @@
+<?php
+
+use App\Models\BackupItem;
+use App\Models\BackupSet;
+use App\Models\Policy;
+use App\Models\Tenant;
+use App\Models\User;
+use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphResponse;
+use App\Services\Intune\RestoreService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+test('settings catalog restore marks manual_required when a setting PATCH returns 404', function () {
+    $policyResponse = new GraphResponse(
+        success: true,
+        data: [],
+        status: 200,
+        errors: [],
+        warnings: [],
+        meta: ['request_id' => 'req-policy', 'client_request_id' => 'client-policy'],
+    );
+
+    $settingResponse = new GraphResponse(
+        success: false,
+        data: ['error' => ['code' => 'NotFound', 'message' => 'Setting missing']],
+        status: 404,
+        errors: [['code' => 'NotFound', 'message' => 'Setting missing']],
+        warnings: [],
+        meta: [
+            'error_code' => 'NotFound',
+            'error_message' => 'Setting missing',
+            'request_id' => 'req-setting-404',
+            'client_request_id' => 'client-setting-404',
+        ],
+    );
+
+    $client = new class($policyResponse, $settingResponse) implements GraphClientInterface
+    {
+        /**
+         * @var array<int, array{policy_type:string,policy_id:string,payload:array}>
+         */
+        public array $applyPolicyCalls = [];
+
+        /**
+         * @var array<int, array{method:string,path:string,payload:array|null}>
+         */
+        public array $requestCalls = [];
+
+        public function __construct(
+            private readonly GraphResponse $policyResponse,
+            private readonly GraphResponse $settingResponse,
+        ) {}
+
+        public function listPolicies(string $policyType, array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
+        public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, ['payload' => []]);
+        }
+
+        public function getOrganization(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
+        public function applyPolicy(string $policyType, string $policyId, array $payload, array $options = []): GraphResponse
+        {
+            $this->applyPolicyCalls[] = [
+                'policy_type' => $policyType,
+                'policy_id' => $policyId,
+                'payload' => $payload,
+            ];
+
+            return $this->policyResponse;
+        }
+
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
+        public function request(string $method, string $path, array $options = []): GraphResponse
+        {
+            $this->requestCalls[] = [
+                'method' => strtoupper($method),
+                'path' => $path,
+                'payload' => $options['json'] ?? null,
+            ];
+
+            return $this->settingResponse;
+        }
+    };
+
+    app()->instance(GraphClientInterface::class, $client);
+
+    $tenant = Tenant::create([
+        'tenant_id' => 'tenant-3',
+        'name' => 'Tenant Three',
+        'metadata' => [],
+    ]);
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-3',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Gamma',
+        'platform' => 'windows',
+    ]);
+
+    $backupSet = BackupSet::create([
+        'tenant_id' => $tenant->id,
+        'name' => 'Backup',
+        'status' => 'completed',
+        'item_count' => 1,
+    ]);
+
+    $payload = [
+        'displayName' => 'Settings Catalog Gamma',
+        'Settings' => [
+            [
+                'id' => 'setting-404',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                    'settingDefinitionId' => 'setting_definition',
+                    'simpleSettingValue' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationStringSettingValue',
+                        'value' => 'test-value',
+                    ],
+                ],
+            ],
+        ],
+    ];
+
+    $backupItem = BackupItem::create([
+        'tenant_id' => $tenant->id,
+        'backup_set_id' => $backupSet->id,
+        'policy_id' => $policy->id,
+        'policy_identifier' => $policy->external_id,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'payload' => $payload,
+    ]);
+
+    $user = User::factory()->create();
+    $this->actingAs($user);
+
+    $service = app(RestoreService::class);
+    $run = $service->execute(
+        tenant: $tenant,
+        backupSet: $backupSet,
+        selectedItemIds: [$backupItem->id],
+        dryRun: false,
+        actorEmail: $user->email,
+        actorName: $user->name,
+    )->refresh();
+
+    expect($run->status)->toBe('partial');
+    expect($run->results[0]['status'])->toBe('manual_required');
+    expect($run->results[0]['settings_apply']['manual_required'])->toBe(1);
+    expect($run->results[0]['settings_apply']['issues'][0]['graph_request_id'])->toBe('req-setting-404');
+
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('settings');
+    expect($client->requestCalls[0]['path'])->toBe('deviceManagement/configurationPolicies/scp-3/settings/setting-404');
+
+    $response = $this->get(route('filament.admin.resources.restore-runs.view', ['record' => $run]));
+    $response->assertOk();
+    $response->assertSee('Setting not found on target policy (404).');
+    $response->assertSee('req-setting-404');
+});

tests/Feature/Filament/SettingsCatalogRestoreTest.php

@@ -0,0 +1,304 @@
+<?php
+
+use App\Models\BackupItem;
+use App\Models\BackupSet;
+use App\Models\Policy;
+use App\Models\Tenant;
+use App\Models\User;
+use App\Services\Graph\GraphClientInterface;
+use App\Services\Graph\GraphResponse;
+use App\Services\Intune\RestoreService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+class SettingsCatalogRestoreGraphClient implements GraphClientInterface
+{
+    /**
+     * @var array<int, array{policy_type:string,policy_id:string,payload:array}>
+     */
+    public array $applyPolicyCalls = [];
+
+    /**
+     * @var array<int, array{method:string,path:string,payload:array|null}>
+     */
+    public array $requestCalls = [];
+
+    /**
+     * @param  array<int, GraphResponse>  $requestResponses
+     */
+    public function __construct(
+        private readonly GraphResponse $applyPolicyResponse,
+        private array $requestResponses = [],
+    ) {}
+
+    public function listPolicies(string $policyType, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, ['payload' => []]);
+    }
+
+    public function getOrganization(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function applyPolicy(string $policyType, string $policyId, array $payload, array $options = []): GraphResponse
+    {
+        $this->applyPolicyCalls[] = [
+            'policy_type' => $policyType,
+            'policy_id' => $policyId,
+            'payload' => $payload,
+        ];
+
+        return $this->applyPolicyResponse;
+    }
+
+    public function getServicePrincipalPermissions(array $options = []): GraphResponse
+    {
+        return new GraphResponse(true, []);
+    }
+
+    public function request(string $method, string $path, array $options = []): GraphResponse
+    {
+        $this->requestCalls[] = [
+            'method' => strtoupper($method),
+            'path' => $path,
+            'payload' => $options['json'] ?? null,
+        ];
+
+        $response = array_shift($this->requestResponses);
+
+        return $response ?? new GraphResponse(true, []);
+    }
+}
+
+test('restore marks settings catalog policy as partial when a setting PATCH fails', function () {
+    $policyResponse = new GraphResponse(
+        success: true,
+        data: [],
+        status: 200,
+        errors: [],
+        warnings: [],
+        meta: ['request_id' => 'req-policy', 'client_request_id' => 'client-policy'],
+    );
+
+    $graphResponse = new GraphResponse(
+        success: false,
+        data: ['error' => ['code' => 'BadRequest', 'message' => 'settings are read-only']],
+        status: 400,
+        errors: [['code' => 'BadRequest', 'message' => 'settings are read-only']],
+        warnings: [],
+        meta: [
+            'error_code' => 'BadRequest',
+            'error_message' => 'settings are read-only',
+            'request_id' => 'req-123',
+            'client_request_id' => 'client-abc',
+        ],
+    );
+
+    $client = new SettingsCatalogRestoreGraphClient($policyResponse, [$graphResponse]);
+
+    app()->instance(GraphClientInterface::class, $client);
+
+    $tenant = Tenant::create([
+        'tenant_id' => 'tenant-1',
+        'name' => 'Tenant One',
+        'metadata' => [],
+    ]);
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-1',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Alpha',
+        'platform' => 'windows',
+    ]);
+
+    $backupSet = BackupSet::create([
+        'tenant_id' => $tenant->id,
+        'name' => 'Backup',
+        'status' => 'completed',
+        'item_count' => 1,
+    ]);
+
+    $payload = [
+        'id' => 'scp-1',
+        'displayName' => 'Settings Catalog Alpha',
+        'version' => 3,
+        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+        'createdDateTime' => '2024-01-01T00:00:00Z',
+        'Settings' => [
+            [
+                'id' => 'setting-1',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                    'settingDefinitionId' => 'setting_definition',
+                    'simpleSettingValue' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationStringSettingValue',
+                        'value' => 'test-value',
+                    ],
+                ],
+            ],
+        ],
+        'assignments' => [
+            ['id' => 'assignment-1'],
+        ],
+        'Platforms' => ['windows'],
+    ];
+
+    $backupItem = BackupItem::create([
+        'tenant_id' => $tenant->id,
+        'backup_set_id' => $backupSet->id,
+        'policy_id' => $policy->id,
+        'policy_identifier' => $policy->external_id,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'payload' => $payload,
+    ]);
+
+    $user = User::factory()->create();
+    $this->actingAs($user);
+
+    $service = app(RestoreService::class);
+    $run = $service->execute(
+        tenant: $tenant,
+        backupSet: $backupSet,
+        selectedItemIds: [$backupItem->id],
+        dryRun: false,
+        actorEmail: $user->email,
+        actorName: $user->name,
+    )->refresh();
+
+    expect($run->status)->toBe('partial');
+    expect($run->results[0]['status'])->toBe('partial');
+    expect($run->results[0]['settings_apply']['failed'])->toBe(1);
+    expect($run->results[0]['settings_apply']['issues'][0]['graph_error_message'])->toContain('settings are read-only');
+    expect($run->results[0]['settings_apply']['issues'][0]['graph_request_id'])->toBe('req-123');
+    expect($run->results[0]['settings_apply']['issues'][0]['graph_client_request_id'])->toBe('client-abc');
+
+    expect($client->applyPolicyCalls)->toHaveCount(1);
+    expect($client->applyPolicyCalls[0]['payload'])->toHaveKey('name');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('id');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('@odata.type');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('version');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('assignments');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('platforms');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('settings');
+
+    expect($client->requestCalls)->toHaveCount(1);
+    expect($client->requestCalls[0]['method'])->toBe('PATCH');
+    expect($client->requestCalls[0]['path'])->toBe('deviceManagement/configurationPolicies/scp-1/settings/setting-1');
+    expect($client->requestCalls[0]['payload'])->toBeArray();
+    expect($client->requestCalls[0]['payload'])->toHaveKey('@odata.type');
+    expect($client->requestCalls[0]['payload'])->not->toHaveKey('id');
+    expect($client->requestCalls[0]['payload']['settingInstance']['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance');
+
+    $response = $this
+        ->get(route('filament.admin.resources.restore-runs.view', ['record' => $run]));
+
+    $response->assertOk();
+    $response->assertSee('settings are read-only');
+    $response->assertSee('req-123');
+});
+
+test('restore success for settings catalog uses strict payload', function () {
+    $graphResponse = new GraphResponse(
+        success: true,
+        data: [],
+        status: 200,
+        errors: [],
+        warnings: [],
+        meta: ['request_id' => 'req-success', 'client_request_id' => 'client-success'],
+    );
+
+    $client = new SettingsCatalogRestoreGraphClient($graphResponse);
+
+    app()->instance(GraphClientInterface::class, $client);
+
+    $tenant = Tenant::create([
+        'tenant_id' => 'tenant-2',
+        'name' => 'Tenant Two',
+        'metadata' => [],
+    ]);
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-2',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Beta',
+        'platform' => 'windows',
+    ]);
+
+    $backupSet = BackupSet::create([
+        'tenant_id' => $tenant->id,
+        'name' => 'Backup',
+        'status' => 'completed',
+        'item_count' => 1,
+    ]);
+
+    $payload = [
+        'displayName' => 'Settings Catalog Beta',
+        'Description' => 'desc',
+        'Platforms' => ['windows'],
+        'Settings' => [
+            [
+                'id' => 'setting-1',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance',
+                    'settingDefinitionId' => 'test_setting',
+                    'choiceSettingValue' => [
+                        'value' => 'test_value',
+                    ],
+                ],
+            ],
+        ],
+    ];
+
+    $backupItem = BackupItem::create([
+        'tenant_id' => $tenant->id,
+        'backup_set_id' => $backupSet->id,
+        'policy_id' => $policy->id,
+        'policy_identifier' => $policy->external_id,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'payload' => $payload,
+    ]);
+
+    $user = User::factory()->create();
+    $this->actingAs($user);
+
+    $service = app(RestoreService::class);
+    $run = $service->execute(
+        tenant: $tenant,
+        backupSet: $backupSet,
+        selectedItemIds: [$backupItem->id],
+        dryRun: false,
+        actorEmail: $user->email,
+        actorName: $user->name,
+    )->refresh();
+
+    expect($run->status)->toBe('completed');
+    expect($client->applyPolicyCalls)->toHaveCount(1);
+    expect($client->applyPolicyCalls[0]['payload'])->toHaveKeys(['name', 'description']);
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('platforms');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('Platforms');
+    expect($client->applyPolicyCalls[0]['payload'])->not->toHaveKey('settings');
+    expect($client->applyPolicyCalls[0]['payload']['name'])->toBe('Settings Catalog Beta');
+    expect($client->applyPolicyCalls[0]['payload']['description'])->toBe('desc');
+
+    expect($client->requestCalls)->toHaveCount(1);
+    expect($client->requestCalls[0]['method'])->toBe('PATCH');
+    expect($client->requestCalls[0]['path'])->toBe('deviceManagement/configurationPolicies/scp-2/settings/setting-1');
+
+    // Ensure we preserved settingInstance @odata.type and stripped ids in the per-setting call
+    expect($client->requestCalls[0]['payload'])->toHaveKey('@odata.type');
+    expect($client->requestCalls[0]['payload']['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationSetting');
+    expect($client->requestCalls[0]['payload'])->not->toHaveKey('id');
+    expect($client->requestCalls[0]['payload']['settingInstance'])->toHaveKey('@odata.type');
+    expect($client->requestCalls[0]['payload']['settingInstance']['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance');
+});

tests/Feature/Filament/SettingsCatalogSettingsTableRenderTest.php

@@ -0,0 +1,78 @@
+<?php
+
+use App\Filament\Resources\PolicyResource;
+use App\Filament\Resources\PolicyVersionResource;
+use App\Models\Policy;
+use App\Models\PolicyVersion;
+use App\Models\Tenant;
+use App\Models\User;
+use Carbon\CarbonImmutable;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+test('settings catalog settings render as a filament table with details action', function () {
+    $tenant = Tenant::create([
+        'tenant_id' => env('INTUNE_TENANT_ID', 'local-tenant'),
+        'name' => 'Tenant One',
+        'metadata' => [],
+        'is_current' => true,
+    ]);
+
+    putenv('INTUNE_TENANT_ID='.$tenant->tenant_id);
+    $tenant->makeCurrent();
+
+    $policy = Policy::create([
+        'tenant_id' => $tenant->id,
+        'external_id' => 'scp-policy-1',
+        'policy_type' => 'settingsCatalogPolicy',
+        'display_name' => 'Settings Catalog Policy',
+        'platform' => 'windows',
+    ]);
+
+    $version = PolicyVersion::create([
+        'tenant_id' => $tenant->id,
+        'policy_id' => $policy->id,
+        'version_number' => 1,
+        'policy_type' => $policy->policy_type,
+        'platform' => $policy->platform,
+        'created_by' => 'tester@example.com',
+        'captured_at' => CarbonImmutable::now(),
+        'snapshot' => [
+            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+            'settings' => [
+                [
+                    'id' => 's1',
+                    'settingInstance' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                        'settingDefinitionId' => 'device_vendor_msft_policy_config_system_minimumpinlength',
+                        'simpleSettingValue' => [
+                            '@odata.type' => '#microsoft.graph.deviceManagementConfigurationIntegerSettingValue',
+                            'value' => 12,
+                        ],
+                    ],
+                ],
+            ],
+        ],
+    ]);
+
+    $user = User::factory()->create();
+
+    $policyResponse = $this->actingAs($user)
+        ->get(PolicyResource::getUrl('view', ['record' => $policy]));
+
+    $policyResponse->assertOk();
+    $policyResponse->assertSee('Definition');
+    $policyResponse->assertSee('Type');
+    $policyResponse->assertSee('Value');
+    $policyResponse->assertSee('Details');
+    $policyResponse->assertSee('fi-ta-table');
+
+    $versionResponse = $this->actingAs($user)
+        ->get(PolicyVersionResource::getUrl('view', ['record' => $version]));
+
+    $versionResponse->assertOk();
+    $versionResponse->assertSee('Normalized settings');
+    $versionResponse->assertSee('Details');
+    $versionResponse->assertSee('fi-ta-table');
+});

tests/Feature/Filament/TenantSetupTest.php

@@ -35,6 +35,11 @@ public function applyPolicy(string $policyType, string $policyId, array $payload
             return new GraphResponse(true, []);
         }
 
+        public function getServicePrincipalPermissions(array $options = []): GraphResponse
+        {
+            return new GraphResponse(true, []);
+        }
+
         public function request(string $method, string $path, array $options = []): GraphResponse
         {
             return new GraphResponse(true, []);

tests/Unit/GraphContractFallbackTest.php

@@ -0,0 +1,66 @@
+<?php
+
+use App\Services\Graph\GraphContractRegistry;
+use App\Services\Graph\GraphLogger;
+use App\Services\Graph\MicrosoftGraphClient;
+use Illuminate\Http\Client\Request;
+use Illuminate\Support\Facades\Http;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    config()->set('graph_contracts.types.deviceConfiguration', [
+        'resource' => 'deviceManagement/deviceConfigurations',
+        'allowed_select' => ['id', 'displayName'],
+        'allowed_expand' => [],
+        'type_family' => ['#microsoft.graph.deviceConfiguration'],
+    ]);
+
+    config()->set('graph.base_url', 'https://graph.microsoft.com');
+    config()->set('graph.version', 'beta');
+    config()->set('graph.tenant_id', 'tenant');
+    config()->set('graph.client_id', 'client');
+    config()->set('graph.client_secret', 'secret');
+    config()->set('graph.scope', 'https://graph.microsoft.com/.default');
+});
+
+it('falls back when capability errors occur on select', function () {
+    $callCount = 0;
+
+    Http::fake([
+        'https://login.microsoftonline.com/*' => Http::response([
+            'access_token' => 'fake-token',
+            'expires_in' => 3600,
+        ], 200),
+        'https://graph.microsoft.com/*' => function (Request $request) use (&$callCount) {
+            $callCount++;
+
+            if ($callCount === 1) {
+                return Http::response([
+                    'error' => [
+                        'code' => 'Request_BadRequest',
+                        'message' => 'Request is invalid due to $select',
+                    ],
+                ], 400);
+            }
+
+            return Http::response(['id' => 'policy-1', 'displayName' => 'Policy'], 200);
+        },
+    ]);
+
+    $client = new MicrosoftGraphClient(
+        logger: app(GraphLogger::class),
+        contracts: app(GraphContractRegistry::class),
+    );
+
+    $response = $client->getPolicy('deviceConfiguration', 'policy-1', [
+        'select' => ['id', 'displayName', 'unsupported'],
+        'tenant' => 'tenant',
+        'access_token' => 'token',
+    ]);
+
+    expect($response->successful())->toBeTrue();
+    expect($callCount)->toBe(2);
+    expect($response->warnings)->not->toBeEmpty();
+});

tests/Unit/GraphContractRegistryActualDataTest.php

@@ -0,0 +1,51 @@
+<?php
+
+use App\Services\Graph\GraphContractRegistry;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    $this->registry = app(GraphContractRegistry::class);
+});
+
+it('preserves @odata.type with actual choiceSettingValue data structure', function () {
+    $settings = [
+        [
+            'id' => '0',
+            'settingInstance' => [
+                '@odata.type' => '#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance',
+                'choiceSettingValue' => [
+                    'value' => 'device_vendor_msft_passportforwork_biometrics_usebiometrics_true',
+                    'children' => [],
+                    'settingValueTemplateReference' => null,
+                ],
+                'settingDefinitionId' => 'device_vendor_msft_passportforwork_biometrics_usebiometrics',
+                'auditRuleInformation' => null,
+                'settingInstanceTemplateReference' => null,
+            ],
+        ],
+    ];
+
+    $sanitized = $this->registry->sanitizeSettingsApplyPayload('settingsCatalogPolicy', $settings);
+
+    expect($sanitized)->toBeArray();
+    expect(count($sanitized))->toBe(1);
+
+    // Top-level id should be stripped
+    expect(array_key_exists('id', $sanitized[0]))->toBeFalse();
+
+    // settingInstance should exist
+    expect(isset($sanitized[0]['settingInstance']))->toBeTrue();
+
+    // @odata.type should be preserved inside settingInstance
+    expect(isset($sanitized[0]['settingInstance']['@odata.type']))->toBeTrue();
+    expect($sanitized[0]['settingInstance']['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance');
+
+    // choiceSettingValue should still exist
+    expect(isset($sanitized[0]['settingInstance']['choiceSettingValue']))->toBeTrue();
+    expect($sanitized[0]['settingInstance']['choiceSettingValue']['value'])->toBe('device_vendor_msft_passportforwork_biometrics_usebiometrics_true');
+
+    // Null values should be preserved (Graph might need them)
+    expect(array_key_exists('settingValueTemplateReference', $sanitized[0]['settingInstance']['choiceSettingValue']))->toBeTrue();
+});

tests/Unit/GraphContractRegistrySettingsApplySanitizerTest.php

@@ -0,0 +1,67 @@
+<?php
+
+use App\Services\Graph\GraphContractRegistry;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    config()->set('graph_contracts.types.settingsCatalogPolicy', [
+        'resource' => 'deviceManagement/configurationPolicies',
+        'allowed_select' => ['id'],
+        'allowed_expand' => [],
+        'type_family' => ['#microsoft.graph.deviceManagementConfigurationPolicy'],
+    ]);
+
+    $this->registry = app(GraphContractRegistry::class);
+});
+
+it('preserves @odata.type in settingInstance and strips ids', function () {
+    $settings = [
+        [
+            'id' => 's-1',
+            'displayName' => 'Setting A',
+            'settingInstance' => [
+                '@odata.type' => '#microsoft.management.configuration.deviceManagementConfigurationSimpleSettingInstance',
+                'simpleSettingValue' => ['value' => 10],
+                'id' => 'si-1',
+            ],
+        ],
+        [
+            'displayName' => 'Setting B',
+            'settingInstance' => [
+                '@odata.type' => '#microsoft.management.configuration.deviceManagementConfigurationChoiceSettingInstance',
+                'choiceSettingValue' => ['value' => 'opt1'],
+                'children' => [
+                    [
+                        'id' => 'c-1',
+                        '@odata.type' => '#child.type',
+                        'someValue' => true,
+                    ],
+                ],
+            ],
+        ],
+    ];
+
+    $sanitized = $this->registry->sanitizeSettingsApplyPayload('settingsCatalogPolicy', $settings);
+
+    expect($sanitized)->toBeArray();
+    expect(count($sanitized))->toBe(2);
+
+    // Top-level ids stripped
+    expect(array_key_exists('id', $sanitized[0]))->toBeFalse();
+
+    // Top-level @odata.type should be added if missing
+    expect(isset($sanitized[0]['@odata.type']))->toBeTrue();
+    expect($sanitized[0]['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationSetting');
+    expect(isset($sanitized[1]['@odata.type']))->toBeTrue();
+    expect($sanitized[1]['@odata.type'])->toBe('#microsoft.graph.deviceManagementConfigurationSetting');
+
+    // @odata.type preserved at settingInstance
+    expect(isset($sanitized[0]['settingInstance']['@odata.type']))->toBeTrue();
+    expect(isset($sanitized[1]['settingInstance']['@odata.type']))->toBeTrue();
+
+    // nested child keeps its @odata.type and stripped id
+    expect(isset($sanitized[1]['settingInstance']['children'][0]['@odata.type']))->toBeTrue();
+    expect(array_key_exists('id', $sanitized[1]['settingInstance']['children'][0]))->toBeFalse();
+});

tests/Unit/GraphContractRegistrySettingsWriteStrategyTest.php

@@ -0,0 +1,30 @@
+<?php
+
+use App\Services\Graph\GraphContractRegistry;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+it('builds settings write method and path from the contract', function () {
+    config()->set('graph_contracts.types.settingsCatalogPolicy', [
+        'settings_write' => [
+            'path_template' => 'deviceManagement/configurationPolicies/{id}/settings/{settingId}',
+            'method' => 'PATCH',
+        ],
+    ]);
+
+    $registry = app(GraphContractRegistry::class);
+
+    expect($registry->settingsWriteMethod('settingsCatalogPolicy'))->toBe('PATCH');
+    expect($registry->settingsWritePath('settingsCatalogPolicy', 'policy-1', 'setting-9'))
+        ->toBe('deviceManagement/configurationPolicies/policy-1/settings/setting-9');
+});
+
+it('returns null when settings write contract is missing', function () {
+    config()->set('graph_contracts.types.settingsCatalogPolicy', []);
+
+    $registry = app(GraphContractRegistry::class);
+
+    expect($registry->settingsWriteMethod('settingsCatalogPolicy'))->toBeNull();
+    expect($registry->settingsWritePath('settingsCatalogPolicy', 'policy-1', 'setting-9'))->toBeNull();
+});

tests/Unit/GraphContractRegistryTest.php

@@ -0,0 +1,106 @@
+<?php
+
+use App\Services\Graph\GraphContractRegistry;
+use App\Services\Graph\GraphResponse;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    config()->set('graph_contracts.types.deviceConfiguration', [
+        'resource' => 'deviceManagement/deviceConfigurations',
+        'allowed_select' => ['id', 'displayName'],
+        'allowed_expand' => ['assignments'],
+        'type_family' => [
+            '#microsoft.graph.deviceConfiguration',
+            '#microsoft.graph.windows10CustomConfiguration',
+        ],
+    ]);
+
+    config()->set('graph_contracts.types.settingsCatalogPolicy', [
+        'resource' => 'deviceManagement/configurationPolicies',
+        'allowed_select' => ['id'],
+        'allowed_expand' => [],
+        'type_family' => ['#microsoft.graph.deviceManagementConfigurationPolicy'],
+        'update_whitelist' => ['name', 'description'],
+        'update_map' => ['displayName' => 'name'],
+        'update_strip_keys' => ['platforms', 'technologies', 'templateReference', 'assignments'],
+        'settings_write' => [
+            'path_template' => 'deviceManagement/configurationPolicies/{id}/settings/{settingId}',
+            'method' => 'PATCH',
+        ],
+    ]);
+
+    $this->registry = app(GraphContractRegistry::class);
+});
+
+it('sanitizes disallowed select and expand values', function () {
+    $result = $this->registry->sanitizeQuery('deviceConfiguration', [
+        '$select' => ['id', 'displayName', 'unsupported'],
+        '$expand' => ['assignments', 'badExpand'],
+    ]);
+    $query = $result['query'];
+    $warnings = $result['warnings'];
+
+    expect($query['$select'])->toBe(['id', 'displayName']);
+    expect($query['$expand'])->toBe(['assignments']);
+    expect($warnings)->not->toBeEmpty();
+});
+
+it('matches derived types within family', function () {
+    expect($this->registry->matchesTypeFamily('deviceConfiguration', '#microsoft.graph.windows10CustomConfiguration'))->toBeTrue();
+    expect($this->registry->matchesTypeFamily('deviceConfiguration', '#microsoft.graph.androidCompliancePolicy'))->toBeFalse();
+});
+
+it('detects capability errors for downgrade', function () {
+    $response = new GraphResponse(
+        success: false,
+        data: [],
+        status: 400,
+        errors: [['message' => 'Request is invalid due to $select']]
+    );
+
+    $shouldDowngrade = $this->registry->shouldDowngradeOnCapabilityError($response, ['$select' => ['displayName']]);
+
+    expect($shouldDowngrade)->toBeTrue();
+});
+
+it('provides contract for settings catalog policies', function () {
+    $contract = config('graph_contracts.types.settingsCatalogPolicy');
+
+    expect($contract)->not->toBeEmpty();
+    expect($contract['resource'])->toBe('deviceManagement/configurationPolicies');
+    expect($this->registry->matchesTypeFamily('settingsCatalogPolicy', '#microsoft.graph.deviceManagementConfigurationPolicy'))->toBeTrue();
+});
+
+it('sanitizes update payloads for settings catalog policies', function () {
+    $payload = [
+        'id' => 'scp-1',
+        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+        'displayName' => 'Config',
+        'Description' => 'desc',
+        'version' => 5,
+        'createdDateTime' => '2024-01-01T00:00:00Z',
+        'settings' => [
+            [
+                'id' => 'setting-1',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                    'settingDefinitionId' => 'setting_definition',
+                    'simpleSettingValue' => ['value' => 'bar'],
+                ],
+            ],
+        ],
+        'Platforms' => ['windows'],
+        'unknown' => 'drop-me',
+    ];
+
+    $sanitized = $this->registry->sanitizeUpdatePayload('settingsCatalogPolicy', $payload);
+
+    expect($sanitized)->toHaveKeys(['name', 'description']);
+    expect($sanitized)->not->toHaveKey('id');
+    expect($sanitized)->not->toHaveKey('@odata.type');
+    expect($sanitized)->not->toHaveKey('version');
+    expect($sanitized)->not->toHaveKey('platforms');
+    expect($sanitized)->not->toHaveKey('settings');
+});

tests/Unit/PolicyNormalizerSettingsCatalogFlattenTest.php

@@ -0,0 +1,92 @@
+<?php
+
+use App\Services\Intune\PolicyNormalizer;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    $this->normalizer = app(PolicyNormalizer::class);
+});
+
+it('flattens settings catalog setting instances into a table', function () {
+    $snapshot = [
+        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+        'settings' => [
+            [
+                'id' => 's1',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                    'settingDefinitionId' => 'device_vendor_msft_policy_config_system_minimumpinlength',
+                    'simpleSettingValue' => [
+                        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationIntegerSettingValue',
+                        'value' => 12,
+                    ],
+                ],
+            ],
+            [
+                'id' => 's2',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance',
+                    'settingDefinitionId' => 'device_vendor_msft_policy_config_system_usebiometrics',
+                    'choiceSettingValue' => [
+                        'value' => 'device_vendor_msft_policy_config_system_usebiometrics_true',
+                    ],
+                ],
+            ],
+            [
+                'id' => 'group',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationGroupSettingCollectionInstance',
+                    'settingDefinitionId' => 'device_vendor_msft_policy_config_system_group',
+                    'groupSettingCollectionValue' => [
+                        [
+                            'children' => [
+                                [
+                                    '@odata.type' => '#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance',
+                                    'settingDefinitionId' => 'device_vendor_msft_policy_config_system_child',
+                                    'simpleSettingValue' => [
+                                        'value' => true,
+                                    ],
+                                ],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+            [
+                'id' => 'unknown',
+                'settingInstance' => [
+                    '@odata.type' => '#microsoft.graph.someUnknownSettingInstance',
+                    'settingDefinitionId' => 'unknown_definition',
+                    'foo' => 'bar',
+                ],
+            ],
+        ],
+    ];
+
+    $result = $this->normalizer->normalize($snapshot, 'settingsCatalogPolicy', 'windows');
+
+    expect($result['status'])->toBe('success');
+    expect($result)->toHaveKey('settings_table');
+
+    $rows = collect($result['settings_table']['rows']);
+
+    $minimumPinLength = $rows->firstWhere('definition', 'device_vendor_msft_policy_config_system_minimumpinlength');
+    expect($minimumPinLength)->not->toBeNull();
+    expect($minimumPinLength['type'])->toBe('SimpleSettingInstance');
+    expect($minimumPinLength['value'])->toBe('12');
+
+    $useBiometrics = $rows->firstWhere('definition', 'device_vendor_msft_policy_config_system_usebiometrics');
+    expect($useBiometrics)->not->toBeNull();
+    expect($useBiometrics['value'])->toContain('usebiometrics_true');
+
+    $child = $rows->firstWhere('definition', 'device_vendor_msft_policy_config_system_child');
+    expect($child)->not->toBeNull();
+    expect($child['value'])->toBe('true');
+    expect($child['path'])->toContain('device_vendor_msft_policy_config_system_group');
+
+    $unknown = $rows->firstWhere('definition', 'unknown_definition');
+    expect($unknown)->not->toBeNull();
+    expect($unknown['value'])->toContain('foo');
+});

tests/Unit/PolicyNormalizerSettingsCatalogTest.php

@@ -0,0 +1,33 @@
+<?php
+
+use App\Services\Intune\PolicyNormalizer;
+use App\Services\Intune\SnapshotValidator;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+beforeEach(function () {
+    $this->normalizer = new PolicyNormalizer(new SnapshotValidator);
+});
+
+it('normalizes settings catalog settings into key value entries', function () {
+    $snapshot = [
+        '@odata.type' => '#microsoft.graph.deviceManagementConfigurationPolicy',
+        'settings' => [
+            ['displayName' => 'Minimum PIN Length', 'value' => 12],
+            ['definitionId' => 'winhello', 'value' => true],
+        ],
+    ];
+
+    $result = $this->normalizer->normalize($snapshot, 'settingsCatalogPolicy', 'windows');
+
+    expect($result['status'])->toBe('success');
+    expect($result)->toHaveKey('settings_table');
+    $rows = $result['settings_table']['rows'];
+    expect($rows[0]['definition'])->toBe('Minimum PIN Length');
+    expect($rows[0]['type'])->toBe('-');
+    expect($rows[0]['value'])->toBe('12');
+    expect($rows[1]['definition'])->toBe('winhello');
+    expect($rows[1]['type'])->toBe('-');
+    expect($rows[1]['value'])->toBe('true');
+});

tests/Unit/PolicyNormalizerTest.php

@@ -1,6 +1,9 @@
 <?php
 
 use App\Services\Intune\PolicyNormalizer;
+use Tests\TestCase;
+
+uses(TestCase::class);
 
 beforeEach(function () {
     $this->normalizer = app(PolicyNormalizer::class);
@@ -55,7 +58,7 @@
 
 it('detects @odata.type mismatch', function () {
     $snapshot = [
-        '@odata.type' => '#microsoft.graph.iosGeneralDeviceConfiguration',
+        '@odata.type' => '#microsoft.graph.targetedManagedAppProtection',
         'displayName' => 'Policy',
     ];