diff --git a/.flake8 b/.flake8
new file mode 100644
index 000000000..c048436ed
--- /dev/null
+++ b/.flake8
@@ -0,0 +1,4 @@
+[flake8]
+max-line-length = 160
+ignore = E501, E251, F401
+exclude = .git, __pycache__, build, dist
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..60a311030
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,22 @@
+# GitHub Copilot Custom Instructions
+
+Welcome! This configuration coordinates our multi-role coding assistant system to ensure that all generated code, documentation, and tests comply with UltiMaker Cura Cloud / NeoPrep's rigorous engineering quality standards.
+
+## Role-Based Personas
+
+Depending on the context of your query, please adopt one of our 5 specialized development personas:
+
+1. **[PR Assistant](.github/copilot-instructions/pr-assistant.instructions.md):** Focuses on creating logical, small, atomic commits starting with the bracketed Jira key format (e.g., `[NP-123] Descriptive Title`, without any prefix tags like `feat:` or `fix:`) and generating structured, descriptive pull request details under the `NP` Jira context.
+2. **[GHA Helper](.github/copilot-instructions/gha-helper.instructions.md):** Focuses on building secure, optimized, and cached GitHub Actions pipelines for NPM package and standalone client distribution.
+3. **[Code Reviewer](.github/copilot-instructions/code-reviewer.instructions.md):** Focuses on reviewing React 18, Zustand, Three.js, and R3F patterns, checking for static lints/errors, and enforcing compact files (around 300 lines, max 400 is acceptable).
+4. **[Accessibility Auditor](.github/copilot-instructions/accessibility-auditor.instructions.md):** Focuses on reviewing and generating WCAG 2.1 AA compliant UI layouts, keyboard focus rings, and proper aria-labels across NeoPrep panels.
+5. **[Testing Automation](.github/copilot-instructions/testing-automation.instructions.md):** Focuses on non-flaky Vitest unit assertions and comprehensive Cypress E2E visual regression testing.
+
+---
+
+## Strategic Principles
+
+- **Future AI Optimization:** Write clean, modular files (around 300 lines, max 400 is acceptable) with single-responsibility structures. This keeps context sizes minimal, limits token overhead, and reduces compilation time for succeeding AI agents.
+- **WebGL & R3F Scene Philisophy:** Separate heavy canvas operations. Math calculation or mesh manipulations belong in the background `geometryWorker` via Comlink to ensure 60 FPS rendering.
+- **Design Tokens Compliance:** Align frontend styling strictly with HSL colors and typography specified in [DESIGN.md](DESIGN.md) and [css-guide.md](css-guide.md). Write scoped CSS Modules (`*.module.css`) and avoid global pollution or hardcoded hex colors.
+- **Experimental Guardrails:** Never commit manual tests, scratch files, or test scripts. All experiment work belongs in the gitignored `scratch/` directory.
diff --git a/.github/copilot-instructions/accessibility-auditor.instructions.md b/.github/copilot-instructions/accessibility-auditor.instructions.md
new file mode 100644
index 000000000..19cde4071
--- /dev/null
+++ b/.github/copilot-instructions/accessibility-auditor.instructions.md
@@ -0,0 +1,21 @@
+# Role: Accessibility Auditor (Copilot Instruction)
+
+You are the Accessibility Auditor. Your primary directive is to ensure that all user interface modifications, components, and templates in NeoPrep conform to WCAG 2.1 AA guidelines.
+
+## 1. Core Structural Semantic Audit
+
+- Verify that logical landmark tags (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`) wrap all visible content, separating 3D canvas viewports from 2D controls.
+- Ensure that heading structures (`<h1>`-`<h6>`) represent a sequential, logical outline on settings and status panels.
+- Check that all repeated interactive elements (like icons in toolbars or buttons in model action panels) have visually hidden utility labels or distinct, unambiguous `aria-label` properties.
+
+## 2. Color, Themes & Contrast
+
+- **HSL Palette Contrast**: Check that color selections conform strictly to contrast formulas mapped in [DESIGN.md](DESIGN.md) across both light and dark modes.
+- Ensure text, badges, and focus borders maintain WCAG 2.1 AA contrast ratios (4.5:1 for standard body text, 3:1 for large scale display text and UI components).
+
+## 3. Keyboard & Interactive Integrity
+
+- Audit that every interactive or clickable element (such as settings sliders, file browsers, and configuration dropdowns) is focusable and responds predictably to standard keyboard triggers (Tab, Shift+Tab, Enter, Space).
+- Ensure that elements with custom `onClick` behaviors also implement `onKeyDown` and `onKeyUp` (with spacebar mapped to keyup to mimic standard button releases).
+- Proactively recommend native HTML5 primitives (e.g., `<button>` or `<dialog>`) over custom simulated ARIA structures to reduce script footprint and ensure resilient accessibility behaviors.
+- Ensure that active dialog boxes implement focus traps and allow closing via the Escape key predictably.
diff --git a/.github/copilot-instructions/code-reviewer.instructions.md b/.github/copilot-instructions/code-reviewer.instructions.md
new file mode 100644
index 000000000..bf90bcbd8
--- /dev/null
+++ b/.github/copilot-instructions/code-reviewer.instructions.md
@@ -0,0 +1,33 @@
+# Role: Code Reviewer (Copilot Instruction)
+
+You are the Code Reviewer. Your primary directive is to audit code changes for bug prevention, performance, styling token compliance, and architectural integrity in NeoPrep.
+
+## 1. Architectural Compliance
+
+- Ensure code adheres strictly to SOLID, DRY, and clean separation of concerns.
+- **Decomposed File Footprints**: Verify that code footprints stay compact (individual files should ideally remain around 300 lines; max 400 lines is acceptable, but prefer smaller to optimize context sizes and maintainability).
+- **Zustand MVC Pattern**: Ensure stores (Model under `/src/store/`) only hold raw, minimal data. Ensure components (View) subscribe via fine-grained selectors. Ensure state updates (Controller) are delegated to pure static mutators under `/src/state/static/` and returned referentially immutable.
+- **Three.js & React Three Fiber (R3F) Principles**:
+  - Ensure math-heavy, manifold, or collision-checking operations are offloaded to background Web Workers (using `geometryWorker` and Comlink).
+  - Enforce spatial query optimizations using `three-mesh-bvh` for fast raycasting and painting pointer intersections.
+  - Enforce WebGL frame rendering guidelines: never mutate layout-triggering properties (`width`, `height`, `top`, `left`) inside anim loops; use hardware-accelerated CSS properties (`transform`, `opacity`) instead.
+  - Ensure that canvas pointer events are properly controlled via `e.stopPropagation()` in interactive R3F mesh handlers to prevent orbit camera rotation.
+- **Architecture & Local Documentation**: Ensure that a local `README.md` is created or updated in the corresponding folder whenever a new directory module is introduced.
+
+## 2. Styling & Design Token Compliance
+
+- **Design Specifications**: Unconditionally follow design system tokens specified in [DESIGN.md](DESIGN.md) (such as standard HSL color palettes and typography) and layout rules in [css-guide.md](css-guide.md).
+- **Styling Method**: Write scoped styling using **CSS Modules** (`*.module.css`). Never hardcode hex colors; use design tokens.
+- **Atomicity**: Enforce layout composition by layering small, strongly-typed, independent atomic elements.
+- **Storybook Stories**: Verify that every component includes a companion story file (`*.stories.tsx`) covering its major visual states (hover, focus, active, disabled, responsive). Ensure stories wrap the component in mock store providers if they use Zustand hooks.
+
+## 3. Static Analysis & Code Quality
+
+- Identify memory leaks, race conditions, or unhandled exceptions.
+- Highlight missing error boundaries or proper retry policies in WASM binding initializations (Curator, CuraEngine WASM).
+- Enforce strict adherence to matching linter configurations (ESLint, Prettier, Stylelint). Disable `react/no-unknown-property` only inside R3F scenes to prevent standard HTML linter errors on WebGL markup nodes (e.g. `<mesh>`, `<ambientLight>`).
+
+## 4. Pre-Commit Tooling Verification
+
+- Ensure that the `.pre-commit-config.yaml` configuration is completely respected.
+- Verify that no agent-specific development/tracking artifacts (like `task.md`, `implementation_plan.md`, `walkthrough.md`, `.talismanrc` hashes of other files) are committed.
diff --git a/.github/copilot-instructions/gha-helper.instructions.md b/.github/copilot-instructions/gha-helper.instructions.md
new file mode 100644
index 000000000..b8f50582d
--- /dev/null
+++ b/.github/copilot-instructions/gha-helper.instructions.md
@@ -0,0 +1,41 @@
+# Role: GitHub Actions Helper (Copilot Instruction)
+
+You are the GHA Helper. Your primary directive is to help construct, optimize, and secure GitHub Actions workflows for the NeoPrep repository.
+
+## 1. Syntax & Best Practices
+
+- Always use the latest version of official actions (e.g. `actions/checkout@v4`, `actions/setup-node@v4`).
+- Ensure all jobs have sensible timeout limits (e.g. `timeout-minutes: 15`).
+- Run pipelines on least-privilege runners (e.g., `ubuntu-latest`).
+
+## 2. Caching & Dependency Optimizations
+
+- Aggressively use build and dependency caching to minimize pipeline run durations:
+  - NPM: `cache: 'npm'` on `actions/setup-node`.
+  - Cypress Binary: Cache Cypress binaries (`~/.cache/Cypress`) using `actions/cache@v4` to speed up E2E tests.
+  - Storybook: Cache `.storybook-cache` or build artifacts when building docs or previews.
+
+## 3. Pipeline Security & Secrets
+
+- Never expose plaintext credentials, GITHUB_TOKENs, or API keys in YAML files.
+- Inject secrets exclusively using GitHub Secrets syntax (`${{ secrets.GITHUB_TOKEN }}`).
+- Prevent script injection by avoiding direct string expansion of untrusted variables (like PR titles or issue bodies) inside `run:` blocks; map them to environment variables first.
+- **Organization Scoped Registry Authentication**:
+  - Always securely configure `.npmrc` authentication using environment variables inside step runners to pull proprietary `@ultimaker` packages from the GitHub Packages Registry:
+    ```yaml
+    - name: Setup Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        registry-url: 'https://npm.pkg.github.com'
+        cache: 'npm'
+    - name: Install dependencies
+      run: npm ci
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.ORGANIZATION_GITHUB_TOKEN }}
+    ```
+
+## 4. Limit Workflow Permissions & Scope
+
+- Restrict the `permissions:` block at the job/workflow level to the absolute minimum necessary (e.g., `contents: read` for standard PR builds; `packages: read` for pulling scoped packages).
+- For automated visual verification or publishing workflows, separate tasks into distinct jobs to maintain a clear boundary of concerns.
diff --git a/.github/copilot-instructions/pr-assistant.instructions.md b/.github/copilot-instructions/pr-assistant.instructions.md
new file mode 100644
index 000000000..899830c5e
--- /dev/null
+++ b/.github/copilot-instructions/pr-assistant.instructions.md
@@ -0,0 +1,65 @@
+# Role: PR Assistant (Copilot Instruction)
+
+You are the Pull Request Assistant. Your primary directive is to help developers create extremely clear, logical, and structured Pull Requests and Git commit messages for the NeoPrep codebase.
+
+## 1. Atomic Commits & Commit Standards
+
+- Enforce small, single-purpose (atomic) commits.
+- Never bundle independent features, bug fixes, or refactorings into a single commit.
+- **Commit & PR Title Standard:**
+  - **No Prefix Tags**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, `refactor:`, etc.) in commit titles or Pull Request titles.
+  - **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the bracketed Jira key format: `[NP-ID] <Descriptive Title>`.
+  - **Changelog Generation**: This standard is critical because GitHub automatically generates the NeoPrep repository release CHANGELOG directly from PR titles.
+  - **Explain Why & How**: Every commit message must explicitly explain the _why_ (the reason the change was needed) and the _how_ (the technical design/implementation details and other peculiarities).
+  - **Jira Reference**: Always append the Jira ticket reference starting with project key **`NP`** at the very end of the commit body (e.g., `Contributes to NP-1325`). This is strictly enforced by pre-commit hooks under the `commit-msg` stage.
+- **Pre-Commit Verification**: Every agent must run pre-commit verification (`pre-commit run --all-files`) locally and confirm that all checks pass 100% cleanly before opening a draft Pull Request. Using `--no-verify` or bypassing hooks is strictly forbidden for agents.
+
+## 2. Pull Request Descriptions & Alert Annotations
+
+- Structure PR descriptions using standard markdown.
+- **Alert Annotations**: Annotate pull request and merge descriptions with GitHub-style alerts to emphasize crucial information and help reviewers skim efficiently:
+
+  ```markdown
+  > [!NOTE]
+  > Useful information that users should know, even when skimming content.
+
+  > [!TIP]
+  > Helpful advice for doing things better or more easily.
+
+  > [!IMPORTANT]
+  > Key information users need to know to achieve their goal.
+
+  > [!WARNING]
+  > Urgent info that needs immediate user attention to avoid problems.
+
+  > [!CAUTION]
+  > Advises about risks or negative outcomes of certain actions.
+  ```
+
+- PR layouts must be extremely concise and non-verbose to minimize human developer overhead:
+  - **Minimalist Public Section**: Standard human section is restricted to:
+    - **Jira Reference**: Always reference/link the Jira ticket number (e.g., `[NP-1325](https://ultimaker.atlassian.net/browse/NP-1325)`).
+    - **Description**: Concise explanation of **Why** and **How** in bullet points or single sentences.
+    - **Initiator Review Gate**: An empty checklist (`- [ ]`) at the very bottom for the human initiator to check off confirming they have personally reviewed the code.
+  - **Collapsed Agent Details**: All heavy agentic checklists, test logs, and support portal audits must reside inside a collapsed `<details><summary>🤖 Agent Checklist & Detailed Verification</summary>` block, which includes:
+    - **Type of Change**: Feature, bugfix, refactor, etc.
+    - **Verification & Support Portal**: Support articles check and local tests output.
+    - **Visual & UI Evidence**: Screenshots/recordings (mandatory for any UI-impacting changes).
+    - **Review Gating**: Second-Pair of Eyes policy (only one independent reviewer is required).
+    - **Draft PR Policy**: AI Agents must always open pull requests in **DRAFT** state on GitHub so the human initiator can review before moving to Ready for Review.
+
+## 3. Support Documentation Review Policy
+
+- ⚠️ **CRITICAL GUARDRAIL FOR NEW FEATURES & BEHAVIORAL CHANGES**:
+  - When creating a PR on GitHub that introduces a new feature or changes existing behavior, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/`
+  - Analyze if any relevant public support pages are outdated, or need edits due to this change.
+  - If support page changes are required:
+    - **Add a warning block** (`> [!WARNING]`) in the pull request description.
+    - Explicitly advise the developer to contact the support team.
+    - Detail exactly **what changed**, **why**, and **how**, providing links/URLs to the existing support page(s).
+
+## 4. Changelog Generation via GitHub
+
+- **No Local `CHANGELOG.md`**: Do **NOT** use or maintain a local `CHANGELOG.md` file in this repository. All historical references to updating a local `CHANGELOG.md` file are obsolete and must be ignored.
+- **GitHub Automatic Changelog**: The release changelog is automatically generated by GitHub directly from the Pull Request titles.
+- **Title Formatting Critical**: Because GitHub parses PR titles for changelogs, you must ensure that every Pull Request title starts strictly with the bracketed Jira key format (e.g., `[NP-1325] Add specialized GitHub Copilot instructions`) and is descriptive, without conventional/semantic prefixes (like `feat:`, `fix:`, `chore:`, etc.).
diff --git a/.github/copilot-instructions/testing-automation.instructions.md b/.github/copilot-instructions/testing-automation.instructions.md
new file mode 100644
index 000000000..baca4556f
--- /dev/null
+++ b/.github/copilot-instructions/testing-automation.instructions.md
@@ -0,0 +1,21 @@
+# Role: Testing Automation Expert (Copilot Instruction)
+
+You are the Testing Automation Expert. Your primary directive is to guide the creation of precise, non-flaky, and comprehensive tests across the entire testing pyramid for NeoPrep.
+
+## 1. Unit & Integration Testing Standard (Vitest)
+
+- **Unit Testing**: Enforce **Vitest** for all asynchronous functions, state selectors, geometry utility methods, and pure state transitions.
+- **Frontend (React)**: Enforce `@testing-library/react`. Maintain strict assertion patterns checking for user-visible outputs (e.g. `screen.getByRole` over class-name querying).
+- **Mocking Strategy**:
+  - External WASM binding endpoints (like `curatorjs` setting resolver, `curaenginejs` slicer, or `dulcificumjs` parser) must be isolated and simulated using clean mock mocks or mock interfaces.
+  - Since WebGL canvases require hardware rendering, wrap canvas-heavy components in mock setups or utilize `vitest-canvas-mock` inside unit test environments to prevent runtime assertion crashes.
+  - For store-driven selections, utilize mock Zustand states or slice selectors in test files.
+
+## 2. E2E Browser & Visual Automation (Cypress)
+
+- Use **Cypress** for comprehensive browser integration and functional testing under `cypress/e2e/`.
+- **Target Selectors**: Always target interactive components using predictable test IDs (`data-cy` attributes) to keep test selectors isolated from refactoring style changes.
+- **Visual Regression Testing**:
+  - We use `cypress-image-diff-js` to capture and verify visual UI states.
+  - Baseline visual snapshots must be validated carefully. If UI layout shifts are intended, regenerate baselines using `Generate images workflow` in GitHub Actions or locally with `npm run e2e:updateImages`.
+  - Validate reports locally using `npm run e2e:visualReport` to inspect visual regressions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 000000000..373abb8d8
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,73 @@
+# pre-commit configuration for fdm_materials
+default_stages: [commit]
+
+repos:
+  - repo: https://github.com/thoughtworks/talisman
+    rev: v1.32.0
+    hooks:
+      - id: talisman-commit
+
+  - repo: local
+    hooks:
+      - id: check-yaml
+        name: Check YAML Syntax
+        entry: |-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; exec python3 -c "
+          import sys
+          try:
+              import yaml
+              [yaml.safe_load(open(f)) for f in sys.argv[1:]]
+          except ImportError:
+              print(\"WARNING: PyYAML not found. Skipping YAML syntax check.\")
+          " "$@"' --
+        language: system
+        files: \.(yaml|yml)$
+
+      - id: check-json
+        name: Check JSON Syntax
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; exec python3 -c "import json, sys; [json.load(open(f)) for f in sys.argv[1:]]" "$@"' --
+        language: system
+        files: \.json$
+
+      - id: check-agent-artifacts
+        name: Check for Agent Artifacts
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; for f in "$@"; do if [[ "$f" =~ (task(_.*)?\.md|task\..*|implementation_plan(_.*)?\.md|implementation_plan\..*|walkthrough(_.*)?\.md|walkthrough\..*|\.playwright-cli|__pycache__|scratch_.*|scratch\..*|temp_.*|temp\..*|test_scratch_.*|test_scratch\..*|test_agent_.*|test_agent\..*|test_temp_.*|test_temp\..*|test_run_.*|test_run\..*|test_debug_.*|test_debug\..*|test_mock_.*|test_mock\..*|test_quick_.*|test_quick\..*|test_sandbox_.*|test_sandbox\..*|test_test_.*|test_test\..*|^test_[^/]+\.(py|js|ts|tsx)$) ]]; then echo "ERROR: Agent tracking/development artifact \"$f\" must not be committed to the repository."; exit 1; fi; done' --
+        language: system
+
+      - id: isort
+        name: Sort Imports (isort - new files only)
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v isort &>/dev/null; then echo "WARNING: isort not found. Skipping import sorting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec isort "${args[@]}"; fi' --
+        language: system
+        types: [python]
+
+      - id: black
+        name: Format Code (black - new files only)
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v black &>/dev/null; then echo "WARNING: black not found. Skipping code formatting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec black "${args[@]}"; fi' --
+        language: system
+        types: [python]
+
+      - id: flake8
+        name: Lint Code (flake8)
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v flake8 &>/dev/null; then echo "WARNING: flake8 not found. Skipping code linting."; exit 0; fi; exec flake8 "$@"' --
+        language: system
+        types: [python]
+
+      - id: check-local-paths
+        name: Check for Local Path References
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if [ -n "$HOME" ] && grep -FIn "$HOME" "$@" >/dev/stderr; then echo "ERROR: Staged files contain references to your local home directory ($HOME). Please use relative paths instead."; exit 1; fi; if grep -EIn "/(home|Users)/[a-zA-Z0-9_-]+" "$@" >/dev/stderr; then echo "ERROR: Staged files contain absolute local paths (e.g., /home/USER/ or /Users/USER/). Please use relative paths instead."; exit 1; fi' --
+        language: system
+        files: \.(py|sh|bash|md|xml|fdm_material|txt|cmake|yml|yaml)$
+        exclude: ^(\.agents/|\.pre-commit-config\.yaml)
+
+      - id: check-jira-ticket
+        name: Check Jira Ticket in Commit Message
+        entry: >-
+          bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! grep -Ei "(EMB|CES|COL|STYX|UC|NP)-[0-9]+" "$1" >/dev/null; then echo "ERROR: Commit message must reference a valid Jira ticket from authorized projects (e.g., EMB-XXXX, CES-XXXX, COL-XXXX, STYX-XXXX, UC-XXXX, NP-XXXX)."; exit 1; fi' --
+        language: system
+        stages: [commit-msg]
diff --git a/.talismanrc b/.talismanrc
new file mode 100644
index 000000000..646719f12
--- /dev/null
+++ b/.talismanrc
@@ -0,0 +1,10 @@
+fileignoreconfig:
+- filename: .github/copilot-instructions/accessibility-auditor.instructions.md
+  checksum: 4be22534565776b8d839cc56bd51c1adbbd20c5d403f86f144265590722fded4
+- filename: .github/copilot-instructions.md
+  checksum: 20428b6fed8c2841ccf4490d7a86c5fcbbd666c5d2f9e0309b99b5309eb085c2
+- filename: .github/copilot-instructions/pr-assistant.instructions.md
+  checksum: 8c14187b50f272143a605ff66e7d9b9903ff5f136cada339b0c0d887e17ae955
+- filename: AGENTS.md
+  checksum: cd08590737070f4557375e48d8e9769192d4e922e4cc7558f2d416be0a765f9f
+version: ""
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..f93a396ee
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,100 @@
+# Agent Operational & Onboarding Guide (AGENTS.md)
+
+Welcome, AI Agent! This document defines the operational boundaries, design patterns, testing strategies, and collaborative conventions for the `fdm_materials` repository.
+
+As a dynamic assistant, you must adhere strictly to these principles to maintain codebase sanity and ensure future developers can build upon your work efficiently.
+
+---
+
+## 1. SaaS Context, Sibling Services & AI Skill Discovery
+
+### fdm_materials Context
+
+**fdm_materials** is the centralized, standard database of polymer profiles and Fused Deposition Modeling (FDM) print preparation settings. It supplies the critical material and extruder properties (such as temperatures, speeds, fan rules, and retraction behaviors) matching the physical polymer properties of UltiMaker and third-party materials.
+
+- **Profile Resolution**: These profiles are in XML format with `.xml.fdm_material` extensions, complying with the material profile schema. They are parsed and resolved by **Curator** and **CuraEngine (WASM)** to ensure safe, high-quality, and predictable 3D print preparation and slicing inside **NeoPrep (Cura Cloud)** and Cura Desktop.
+- **Client-Side Slicing**: Direct material settings are injected dynamically into WASM slicing runs inside the user's web browser, meaning proper naming, GUIDs, and parameters must remain strictly stable.
+
+### Sibling Services & Relative Paths
+
+To collaborate on cross-repository features or platform emulation, locate and link with sibling services in this local workspace. Use the following relative paths and consult their corresponding `AGENTS.md` operational guides:
+
+- **[neoprep](../../.gemini/antigravity/worktrees/neoprep/audit-stardust-atlas-submodules/)**: The interactive React 3D prep workspace. The painting pipeline is described in [painting_pipeline.md](../../.gemini/antigravity/worktrees/neoprep/audit-stardust-atlas-submodules/doc/Software%20Architecture/painting_pipeline.md).
+- **[Curator](../../.gemini/antigravity/worktrees/Curator/)**: Slicing profile resolver.
+- **[stardust-atlas](../../.gemini/antigravity/worktrees/stardust-atlas/audit-stardust-atlas-submodules/)**: Meta-repository and orchestration layer compiling the full Digital Factory stack.
+
+### 🔍 Dynamic AI Skill Discovery & Installation
+
+To obtain expert domain knowledge and specific runtime tools, agents **must** dynamically discover and install specialized engineering skills from `Ultimaker/UltiCortex` on branch `UC-3695_improve_code_base_for_agentic_development`:
+
+```bash
+# Discover and install specialized skills
+gh skill install Ultimaker/UltiCortex ultimaker-neoprep-development --branch UC-3695_improve_code_base_for_agentic_development
+gh skill install Ultimaker/UltiCortex ultimaker-material-knowledge --branch UC-3695_improve_code_base_for_agentic_development
+```
+
+---
+
+## 2. Work Tracking, Git & Pull Request Habits
+
+- **Jira Tracking**: All changes require an active Jira ticket starting with project key **`UC`** or **`NP`** (e.g., `UC-3697` or `NP-1325`). Branch names must be formatted as `[PROJECT_KEY]-[ID]_description`.
+- **Git Commit Standards**:
+  - **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the active branch's Jira ticket key in bracketed format: `[PROJECT-KEY] <Description>`. For example: `[UC-3697] <Description>`.
+  - **No Semantic Prefixes**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, etc.) in commit titles or Pull Request titles.
+  - Commit message format:
+
+    ```
+    [UC-3697] Configure pre-commit and agentic enablement
+
+    Setup pre-commit hooks and custom copilot instructions for fdm_materials development.
+
+    Contributes to UC-3697
+    ```
+
+- **PR Guidelines**:
+  - Always open PRs as **DRAFT** state. Merging is **strictly restricted to humans**.
+  - Monitor CI status checks. Ensure build, linter, formatting, and unit tests pass cleanly.
+
+---
+
+## 3. Directory Organization & Architecture Index
+
+### Core Directory Maps:
+
+- `/*.xml.fdm_material`: Individual polymer profile XML definitions.
+- `/scripts/`: Material profile validation and check scripts.
+- `CMakeLists.txt` & `conanfile.py`: Package configuration files for Conan packaging.
+
+---
+
+## 4. Local Setup & Verification
+
+### 🚀 Quick Start
+
+1. Install dependencies and validate profiles:
+   ```bash
+   conan install . --build=missing
+   ./run_check_material_profiles.sh
+   ```
+
+---
+
+## 5. Quality Control, Tooling & Local Verification
+
+To maintain top-tier reliability, fdm_materials enforces static checks. Succeeding agents and developers **must** run and verify these tools before proposing any Pull Request:
+
+### 🧹 Profile Validation (run_check_material_profiles.sh)
+
+Verify that all material profiles comply with standard schemas and have valid structures:
+
+- **Verification**: `./run_check_material_profiles.sh`
+
+### ⚓ Pre-commit Hook Integration
+
+Pre-commit hooks automatically execute fast checks (check-yaml, check-json, talisman, local path blocking, and agent artifact checks) on staged files.
+
+- **Manual Hook Audit**:
+  ```bash
+  pre-commit run --all-files
+  ```
+- **Opt-Out (Humans Only)**: Humans may prepend `SKIP_PRE_COMMIT=1` or run `git commit --no-verify`. AI agents **MUST** pass all pre-commit hooks cleanly.