From b55ea1e3029bc6c6eb597f1aba17dfaf5488d620 Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Wed, 15 Apr 2026 15:50:42 +0800
Subject: [PATCH 1/7] initial ai setup

---
 .claude/agents/java-build-resolver.md         | 132 ++++++++
 .claude/agents/java-reviewer.md               | 144 ++++++++
 .claude/agents/react-reviewer.md              | 140 ++++++++
 .claude/commands/gradle-build.md              |  74 ++++
 .claude/commands/verify.md                    |  96 ++++++
 .claude/docs/FORK_MAINTENANCE.md              | 262 +++++++++++++++
 .claude/hooks/enforce-custom-path.sh          | 100 ++++++
 .claude/rules/custom-package-isolation.md     | 144 ++++++++
 .claude/rules/groovy/patterns.md              | 314 +++++++++++++++++
 .claude/rules/groovy/testing.md               | 239 +++++++++++++
 .claude/rules/java/coding-style.md            | 127 +++++++
 .claude/rules/java/hooks.md                   |  22 ++
 .claude/rules/java/patterns.md                | 150 +++++++++
 .claude/rules/java/security.md                |  94 ++++++
 .claude/rules/web/coding-style.md             | 108 ++++++
 .claude/rules/web/design-quality.md           |  67 ++++
 .claude/rules/web/patterns.md                 | 166 +++++++++
 .claude/rules/web/performance.md              |  81 +++++
 .claude/rules/web/security.md                 |  63 ++++
 .claude/rules/web/testing.md                  | 120 +++++++
 .claude/settings.json                         |  17 +
 .claude/skills/code-review/SKILL.md           |  40 +++
 .../skills/customs-trade-compliance/SKILL.md  | 263 +++++++++++++++
 .../skills/inventory-demand-planning/SKILL.md | 247 ++++++++++++++
 .../logistics-exception-management/SKILL.md   | 222 ++++++++++++
 .../skills/openboxes-domain-model/SKILL.md    | 318 ++++++++++++++++++
 .claude/skills/production-scheduling/SKILL.md | 238 +++++++++++++
 .../skills/quality-nonconformance/SKILL.md    | 260 ++++++++++++++
 .../skills/returns-reverse-logistics/SKILL.md | 240 +++++++++++++
 .gitignore                                    |   2 +
 CLAUDE.md                                     | 224 ++++++++++++
 docker/docker-compose.yml                     |   4 +
 docker/openboxes-config.properties            |  32 ++
 openspec/config.yaml                          | 117 +++++++
 package-lock.json                             |  38 +--
 35 files changed, 4886 insertions(+), 19 deletions(-)
 create mode 100644 .claude/agents/java-build-resolver.md
 create mode 100644 .claude/agents/java-reviewer.md
 create mode 100644 .claude/agents/react-reviewer.md
 create mode 100644 .claude/commands/gradle-build.md
 create mode 100644 .claude/commands/verify.md
 create mode 100644 .claude/docs/FORK_MAINTENANCE.md
 create mode 100755 .claude/hooks/enforce-custom-path.sh
 create mode 100644 .claude/rules/custom-package-isolation.md
 create mode 100644 .claude/rules/groovy/patterns.md
 create mode 100644 .claude/rules/groovy/testing.md
 create mode 100644 .claude/rules/java/coding-style.md
 create mode 100644 .claude/rules/java/hooks.md
 create mode 100644 .claude/rules/java/patterns.md
 create mode 100644 .claude/rules/java/security.md
 create mode 100644 .claude/rules/web/coding-style.md
 create mode 100644 .claude/rules/web/design-quality.md
 create mode 100644 .claude/rules/web/patterns.md
 create mode 100644 .claude/rules/web/performance.md
 create mode 100644 .claude/rules/web/security.md
 create mode 100644 .claude/rules/web/testing.md
 create mode 100644 .claude/settings.json
 create mode 100644 .claude/skills/code-review/SKILL.md
 create mode 100644 .claude/skills/customs-trade-compliance/SKILL.md
 create mode 100644 .claude/skills/inventory-demand-planning/SKILL.md
 create mode 100644 .claude/skills/logistics-exception-management/SKILL.md
 create mode 100644 .claude/skills/openboxes-domain-model/SKILL.md
 create mode 100644 .claude/skills/production-scheduling/SKILL.md
 create mode 100644 .claude/skills/quality-nonconformance/SKILL.md
 create mode 100644 .claude/skills/returns-reverse-logistics/SKILL.md
 create mode 100644 CLAUDE.md
 create mode 100644 docker/openboxes-config.properties
 create mode 100644 openspec/config.yaml

diff --git a/.claude/agents/java-build-resolver.md b/.claude/agents/java-build-resolver.md
new file mode 100644
index 00000000000..72018b479ce
--- /dev/null
+++ b/.claude/agents/java-build-resolver.md
@@ -0,0 +1,132 @@
+---
+name: java-build-resolver
+description: Fixes Gradle, Groovy, and Java build/compile errors in the OpenBoxes EST fork (Grails 3.3.16 / Groovy 2.4.21 / Java 8 / Gradle 4.10.3). Diagnoses compilation failures, dependency resolution problems, and Grails/Liquibase startup errors with minimal, surgical changes. Use when ./gradlew fails.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Grails / Gradle Build Resolver — OpenBoxes
+
+You fix build errors in the OpenBoxes EST fork. **Surgical changes only** — repair the build, do not refactor.
+
+## Stack constraints (frozen by upstream)
+
+| Layer | Version | Notes |
+|---|---|---|
+| JDK | **OpenJDK 8** | NOT 11, NOT 17. Several plugins break on newer JDKs. |
+| Groovy | 2.4.21 | No `::`, no `!in`, no `!instanceof`, no switch arrow. |
+| Grails | 3.3.16 | Grails Wrapper Gradle distribution = 4.10.3. |
+| Gradle | 4.10.3 | Does not run on JDK 11+. |
+| Build tool | **Gradle only** | No Maven, no `pom.xml`, no `mvnw`. |
+| GORM | 5.2.18 (Hibernate 5.2.18) | |
+| MySQL | 8 (MariaDB 10.3 also supported) | |
+| Liquibase | via Grails Database Migration plugin | |
+
+**If the user reports build errors, the very first thing to check is `java -version` and `./gradlew --version`.** A wrong JDK is by far the most common cause and produces opaque reflective errors (e.g. the well-known `gradle-git-properties` `NormalizeEOLOutputStream.out` failure on JDK 17).
+
+## When invoked
+
+1. Read the error message carefully. Identify which Gradle task failed and what file/line it points at.
+2. Run the **smallest** diagnostic that confirms the cause (see table below).
+3. Apply the smallest fix that resolves it.
+4. Re-run the same task. If green, run the next task in the build chain.
+5. Stop and report to user if the fix would touch upstream files non-surgically — ask for confirmation first.
+
+## Diagnostic commands
+
+```bash
+# Environment sanity (always run first if anything looks reflective/odd)
+java -version
+./gradlew --version
+echo "JAVA_HOME=$JAVA_HOME"
+
+# Compile pipeline (run in this order — earlier failures cascade)
+./gradlew compileJava 2>&1 | tail -50
+./gradlew compileGroovy 2>&1 | tail -50
+./gradlew classes 2>&1 | tail -50
+
+# Test pipeline
+./gradlew test 2>&1 | tail -80
+./gradlew integrationTest 2>&1 | tail -80
+
+# Run the app
+./gradlew bootRun 2>&1 | tail -100
+./gradlew bootRun -Dgrails.env=development 2>&1 | tail -100
+
+# Build artifacts
+./gradlew assemble 2>&1 | tail -50
+./gradlew war 2>&1 | tail -50
+./gradlew prepareDocker -Dgrails.env=prod 2>&1 | tail -80
+
+# Dependency inspection
+./gradlew dependencies --configuration runtime 2>&1 | head -120
+./gradlew dependencyInsight --dependency <name> --configuration runtime
+./gradlew buildEnvironment 2>&1 | head -50
+
+# Caches and cleaning
+./gradlew clean
+./gradlew --refresh-dependencies
+rm -rf .gradle/ build/                          # nuclear; ask user first
+```
+
+## Common error → cause → fix table
+
+| Error / symptom | Likely cause | Surgical fix |
+|---|---|---|
+| `No such property: out for class: com.gorylenko.writer.NormalizeEOLOutputStream` | Running `gradle-git-properties 2.2.4` on JDK 11+ — strong encapsulation blocks the reflective access it does on `FilterOutputStream.out`. | Switch to **JDK 8**. Set `org.gradle.java.home=/usr/lib/jvm/java-8-openjdk-amd64` in `~/.gradle/gradle.properties` (user-global, not repo file). Do **not** upgrade the plugin — the project is on Gradle 4.10.3 and a newer plugin pulls in incompatible Gradle APIs. |
+| `Unsupported class file major version 5[5-9]` | Class compiled with JDK 11/17 being read by JDK 8 toolchain, or vice versa. | Align JDK. Wipe `build/` and `.gradle/`, rebuild on JDK 8. |
+| `Could not initialize class … sun.security.…` / `IllegalAccessError` from any plugin | JDK 17 strong encapsulation against a Gradle 4.x plugin. | Use JDK 8. |
+| `unable to resolve class org.pih.warehouse.…` | Groovy compile failure — usually a Java helper that didn't compile yet (compileJava runs before compileGroovy). | Run `./gradlew compileJava` and fix the underlying Java error first. |
+| `unable to resolve class …` for a brand-new file | Wrong package declaration vs. file path, or new file added outside the source set. Confirm the file is under `grails-app/{services,domain,controllers,...}/org/pih/warehouse/custom/<feature>/` AND the `package` line matches. |
+| `BUG! exception in phase 'semantic analysis'` (Groovy) | Groovy 3+ syntax in a `.groovy` file (e.g. `::` method ref, `!in`, switch arrow). | Rewrite to Groovy 2.4 syntax. |
+| `Liquibase: ChangeSet … already executed but has been changed` | Edited an already-applied changeset. Liquibase computes a checksum at first run. | NEVER edit an applied changeset. Add a new one that performs the correction. If the change is local-only and the dev hasn't deployed, `clearCheckSums` against their local DB is acceptable. |
+| `Liquibase: cannot find changeSet … in changelog` | New custom migration not included from `grails-app/migrations/changelog.groovy`. | Check that `grails-app/migrations/custom/changelog.groovy` is included via a single `include file: 'custom/changelog.groovy'` line in the master, and that the new file is referenced inside `custom/changelog.groovy`. |
+| `bootRun` hangs at `:bootRun` with no output | Asset-pipeline rebuilding everything, or Grails waiting on plugin downloads. | Check `~/.grails/` and `.gradle/caches/` are writable; first run is slow; subsequent runs are <30s. If truly hung > 5min, check for lock files in `.gradle/` and `~/.grails/`. |
+| `Could not resolve all files for configuration ':compileClasspath'` after a long pause | Network / proxy issue or stale snapshot. | `./gradlew --refresh-dependencies`. If behind a corporate proxy, check `~/.gradle/gradle.properties` for `systemProp.https.proxyHost`. |
+| `webpack` step fails inside `./gradlew assemble` or `prepareDocker` | Frontend (Node 14, npm 6–7) build failing. | From the **repo root** (`package.json` lives there, not under `src/main/webapp/`): `rm -rf node_modules && npm install && npm run build`. Must be Node 14. Then re-run the gradle task. |
+| `org.fusesource.jansi …` / `JansiLoader` errors on Linux | Terminal capability issue with Gradle 4.10.3 and modern shells. | Add `--console=plain` to the gradle command. |
+| `prepareDocker` produces no `build/docker/` | Task didn't run because earlier task failed silently. | Run with `--info` and check the output of `bootWar` and `prepareDocker` independently. |
+
+## Grails-specific gotchas
+
+- **`./gradlew bootRun` is the dev runner**, not `grails run-app` (the standalone Grails CLI is not used in this project).
+- **`./gradlew war`** produces `build/libs/openboxes-<version>.war` — used by the WAR-style deploy.
+- **`./gradlew prepareDocker -Dgrails.env=prod`** stages files under `build/docker/` for `docker build`. If this fails, almost always a JDK or Node version issue (see above).
+- **`./gradlew test` runs Spock unit specs**; **`./gradlew integrationTest` runs `@Integration` specs** with a real Grails context — much slower, much more reliable.
+- **No `application.yml` overrides at runtime via `--spring.config.location`.** Grails uses `application.groovy` and external config — overrides go via `-Dgrails.config.locations=…` or env vars listed in `docker/openboxes-config.properties`.
+
+## Java helper compile errors (`src/main/java/`)
+
+- **Java 8 syntax only.** If you see `var`, `record`, `sealed`, `List.of(...)`, `String.isBlank()`, text blocks, switch expressions — those are the cause. Rewrite to Java 8.
+- **No `@Entity`, `@Column`, `@Repository`.** Strip them — GORM owns persistence.
+- **JSR-305 nullness annotations** (`@Nullable`, `@Nonnull`) are on the classpath via Spring/Grails — they're fine to use.
+
+## When you must touch a build file
+
+The build files `build.gradle`, `gradle.properties`, `settings.gradle`, `gradle/wrapper/gradle-wrapper.properties` are **upstream**. Edits to them cause merge conflicts. Before editing:
+
+1. Can the fix go in `~/.gradle/gradle.properties` (user-global) instead? (e.g. JDK pin, proxy settings.) **Yes → do that.**
+2. Can the fix go in a **new** file (e.g. `gradle/init.d/<name>.gradle`)? **Yes → do that.**
+3. Otherwise, make the smallest possible edit, and tell the user the touch point must be added to the OpenSpec change's `design.md` "Upstream touch points" section.
+
+## Stop conditions
+
+Stop and report if:
+- Same error persists after 3 fix attempts.
+- Fix would require a non-surgical edit to an upstream `build.gradle` / `application.groovy` / `application.yml`.
+- Cause is a missing private credential, license, or external service (user must decide).
+- Cause is JDK > 8 and the user can't or won't switch (point them at the existing `build.gradle:105-106` `sourceCompatibility/targetCompatibility = 1.8` lines and the well-known plugin incompatibilities).
+
+## Output format
+
+```
+[FIXED]    <task>  →  <file>:<line>
+           Cause: <one line>
+           Fix:   <one line>
+
+[REMAINS]  <task>  →  <error summary>
+           Next:  <one-line plan>
+
+Build status: SUCCESS / PARTIAL / FAILED
+Files modified: <list — ALL should be inside custom/ unless explicitly justified>
+```
diff --git a/.claude/agents/java-reviewer.md b/.claude/agents/java-reviewer.md
new file mode 100644
index 00000000000..4796087b04d
--- /dev/null
+++ b/.claude/agents/java-reviewer.md
@@ -0,0 +1,144 @@
+---
+name: java-reviewer
+description: Reviews Grails/Groovy and Java helper changes in OpenBoxes. Enforces GORM patterns, custom-package isolation, transactional-by-default services, Spock test quality, and the Java 8 / Groovy 2.4 language floors. MUST BE USED for every backend change under grails-app/, src/main/groovy/, src/main/java/, src/test/groovy/, src/integration-test/groovy/.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a senior Grails/Groovy reviewer for the **OpenBoxes EST fork**. You report findings only — you do not refactor or rewrite code.
+
+OpenBoxes is a fork of upstream PIH OpenBoxes. **The single most important rule is upstream-merge safety.** Every custom line of code must live under `org.pih.warehouse.custom.*` (or a `custom/` subfolder for migrations / GSP / i18n). If a change touches an upstream file, the edit must be surgical and documented. See `rules/custom-package-isolation.md`.
+
+## Stack you are reviewing against
+
+- Grails 3.3.16 / Groovy 2.4.21 / **Java 8** / GORM-Hibernate 5.2.18
+- Spock for tests, Liquibase for migrations, Gradle 4.10.3 build
+- No Spring Boot stereotypes on new beans, no JPA annotations, no Maven
+
+## When invoked
+
+1. `git diff -- 'grails-app/**' 'src/main/groovy/**' 'src/main/java/**' 'src/test/groovy/**' 'src/integration-test/groovy/**'`
+2. `git status -s` — note any newly-added files; check that their **path** lives under a `custom/` folder.
+3. Read `rules/groovy/patterns.md`, `rules/groovy/testing.md`, `rules/custom-package-isolation.md`, `rules/java/patterns.md`, `rules/java/security.md` to anchor your review.
+4. Begin review.
+
+## Review priorities
+
+### CRITICAL — Upstream-merge safety (fork rule)
+
+- **New backend file outside a `custom/` package.** Any new `.groovy` file under `grails-app/{domain,services,controllers,taglib,jobs}/org/pih/warehouse/` whose path does **not** include `custom/` is a blocker. Same for `.java` under `src/main/java/org/pih/warehouse/` not in `custom/`. Same for `.groovy` under `src/main/groovy/org/pih/warehouse/` not in `custom/`. Same for tests under `src/test/groovy/` and `src/integration-test/groovy/`.
+- **New Liquibase migration outside `grails-app/migrations/custom/`.** Filename must be date-prefixed (e.g. `2026-04-15-add-ims-fields.groovy`). The aggregator is `grails-app/migrations/custom/changelog.groovy`, included once from `grails-app/migrations/changelog.groovy`. Edits to upstream changelog files (other than that single include line) are blockers.
+- **Edits to upstream files that are not surgical.** Check the diff: any reformatting, import reordering, or symbol renames in upstream files (anything outside `custom/`) is a blocker. The Boy Scout Rule is **suspended** for upstream files. Only the lines the feature requires may change.
+- **Undocumented upstream touch points.** If the change touches upstream files, the matching OpenSpec change folder (`openspec/changes/<change>/design.md`) must list every modified upstream file under an "Upstream touch points" section. Flag the change for spec update if missing.
+
+### CRITICAL — Security
+
+- **SQL/HQL injection.** GString interpolation in `executeQuery`, `find`, `findAll`, `executeUpdate`, or raw SQL via `Sql` instances. Must use named parameters (`:param`) or positional placeholders, never `"... ${userInput} ..."`.
+- **Path traversal.** User-controlled input passed to `new File(...)`, `Files.newInputStream(...)`, or asset/resource lookups without canonical-path validation.
+- **Command injection.** User input passed to `"command".execute()` or `ProcessBuilder` without validation.
+- **Hardcoded secrets.** API keys, tokens, DB passwords in `.groovy`, `.java`, `.gsp`, or `application.groovy`. Must come from external config / env.
+- **PII / token logging.** `log.info`/`log.debug` near auth/session code that exposes passwords, tokens, session IDs, or full user records.
+- **Mass-assignment.** `domain.properties = params` or `new Foo(params)` without explicit `bindData(domain, params, [include: [...]])` exposes every property to the request.
+- **CSRF token bypass.** Custom controllers that disable the CSRF filter without a documented reason.
+
+If any CRITICAL security issue is found, stop and report it to the user before continuing the review.
+
+### HIGH — Grails architecture
+
+- **`@Autowired` or constructor injection** on a Grails service/controller/taglib. Grails uses convention-based property injection — declare dependencies as `def fooService` (or typed: `FooService fooService`). Constructor injection breaks Grails proxy semantics.
+- **Business logic in controllers.** Controllers in `grails-app/controllers/` must parse input, delegate to a service, and render. Calculations, multi-step workflows, and direct domain queries beyond simple `Foo.get(id)` are smells.
+- **`@Transactional` annotation on a service.** Grails services are **transactional by default**. Adding `@grails.transaction.Transactional` either does nothing or *narrows* transactional scope to just the annotated methods (the rest become non-transactional). Either remove the annotation or use `@NotTransactional` / `@Transactional(readOnly = true)` deliberately and explain why.
+- **JPA annotations on domain classes.** `@Entity`, `@Table`, `@Column`, `@Id`, `@GeneratedValue`, `@OneToMany`, `@JoinColumn`, `@Repository` — all wrong here. Use GORM `static mapping {}`, `static constraints {}`, `static hasMany`, `belongsTo`.
+- **`@Service` / `@Component` / `@Repository` on new classes** under `grails-app/`. Grails auto-discovers by convention; these annotations are noise at best, footguns at worst (they bypass Grails proxying).
+- **N+1 query pattern.** A loop that calls a domain getter on a collection (`shipments.each { it.shipmentItems.size() }`) without a `fetch: 'eager'` mapping or an explicit `criteria { fetchMode 'shipmentItems', FetchMode.JOIN }`. Flag and suggest a single criteria query.
+- **Unbounded list endpoints.** Controllers returning `Foo.list()` or `Foo.findAll()` with no `[max:, offset:]` and no UI-side pagination. Will OOM at scale.
+- **Raw SQL without justification.** `groovy.sql.Sql` or `executeUpdate` with literal SQL when GORM dynamic finders, criteria, or HQL would do. Acceptable if commented with the reason (perf, cross-schema, bulk operation).
+
+### HIGH — Domain / GORM
+
+- **Dynamic finder typos / missing indexes.** `findByCodeAndStatusAndOrgUnit` against unindexed columns will table-scan. Cross-reference with `static mapping { … index … }` or migrations.
+- **Cascading `delete-orphan` on associations the UI exposes.** Easy to nuke shared data accidentally. Confirm intent.
+- **`hasMany` without `belongsTo`** — orphaned children, no cascade, surprises in cleanup.
+- **Bidirectional associations missing `mappedBy`** — Hibernate creates a join table you didn't want.
+- **Constraint-block validations duplicated in service code** instead of relying on `domain.validate()` / `save(failOnError: true)`.
+
+### HIGH — Java helpers (`src/main/java/`)
+
+- **Java 11+ syntax.** `var`, records, sealed classes, `List.of()`, `Map.of()`, `String.isBlank()`, text blocks, switch expressions, pattern matching. **Java 8 only.**
+- **Field injection / Spring stereotypes** (`@Autowired`, `@Service`, `@Component`, `@Repository`) on new classes. Use Grails convention injection from the calling Groovy code, or register beans in `grails-app/conf/spring/resources.groovy`.
+- **JPA annotations.** Same as above — GORM owns persistence.
+- **`System.out.println` / `printStackTrace()`** — use SLF4J.
+
+### MEDIUM — Concurrency and state
+
+- **Mutable instance fields on a Grails service.** Services are singletons by default. Any non-`final` instance state is a race condition.
+- **`@Async` / thread-pool usage** without an explicit executor — defaults are unbounded.
+- **Quartz `@Scheduled` jobs** that take longer than their interval and block the scheduler thread.
+
+### MEDIUM — Groovy idioms (Boy Scout-able only inside `custom/`)
+
+- **Java-style `for` loops** in `.groovy` files where `.each`, `.collect`, `.findAll`, `.groupBy`, `.find`, `.any`, `.every`, or `.inject` would be idiomatic.
+- **`java.util.stream.Stream` usage** in Groovy — Streams are not idiomatic in Groovy 2.4. Use Groovy collection methods.
+- **Groovy 3+ syntax.** Method references (`::`), `!in`, `!instanceof`, switch arrow, multi-catch with `|` outside Groovy 2.4 support — **all forbidden**.
+- **Groovy truth surprises.** `if (collection)` is false for empty *and* null. `0`, `""`, `[]`, `[:]` are all falsy. Flag if the intent was clearly null-check only.
+
+### MEDIUM — Tests (Spock + Grails)
+
+- **Test file outside `src/test/groovy/org/pih/warehouse/custom/<feature>/`** (unit) or `src/integration-test/groovy/org/pih/warehouse/custom/<feature>/` (integration). Tests for upstream code we're modifying still live in our custom tree.
+- **Weak `expect:` assertions.** `result != null`, `result.size() > 0` — replace with concrete equality.
+- **Spock specs missing `where:` blocks** for behavior that varies by input. Data-driven tables are the Spock idiom.
+- **`@TestFor` / `@Mock` / `@TestMixin`** without the corresponding GORM/Spring fixture for the layer under test.
+- **Integration tests using mocked services** instead of `@Integration` real Grails context.
+- **`Thread.sleep` in tests.** Use `PollingConditions` (Spock) or `await` blocks.
+- **Test names that describe the method, not the behavior.** `def "test save"` → `def "save returns persisted entity when constraints valid"`.
+
+### MEDIUM — Liquibase migrations
+
+- **Missing `id`, `author`, `dbms`** attributes on a changeSet.
+- **`<sqlFile>` referencing a path that doesn't exist** under `grails-app/migrations/`.
+- **Destructive change** (`dropColumn`, `dropTable`, `<sql>DELETE…</sql>`) without a `rollback` block.
+- **Index/constraint naming collisions** with upstream — prefix custom names (`fk_custom_...`, `idx_custom_...`).
+
+## Diagnostic commands
+
+```bash
+# What changed
+git diff -- 'grails-app/**' 'src/main/groovy/**' 'src/main/java/**' 'src/test/groovy/**' 'src/integration-test/groovy/**' 'grails-app/migrations/**'
+git status -s
+
+# Targeted greps
+grep -rn "@Autowired" grails-app/ src/main/                          # should be empty in new code
+grep -rn "@Entity\|@Column\|@Repository" grails-app/domain/          # should be empty
+grep -rn "@grails.transaction.Transactional" grails-app/services/    # most uses are smells
+grep -rn "FetchMode\.JOIN\|fetch:\s*'eager'" grails-app/             # context for N+1 review
+grep -rn "executeQuery\|executeUpdate" grails-app/services/          # raw HQL audit
+
+# Compile / test (only if user asks for verification)
+./gradlew compileGroovy
+./gradlew test
+./gradlew integrationTest
+```
+
+## Approval criteria
+
+- **Approve**: no CRITICAL or HIGH issues, custom-isolation rule respected.
+- **Warning**: only MEDIUM issues.
+- **Block**: any CRITICAL (especially upstream-isolation violations) or HIGH issues.
+
+## Output format
+
+```
+[BLOCK]   <path>:<line>  <category> — <one-line description>
+[WARN]    <path>:<line>  <category> — <one-line description>
+[NOTE]    <path>:<line>  <category> — <one-line description>
+
+Custom-isolation: PASS / FAIL (list violations)
+Approval: APPROVE / WARN / BLOCK
+```
+
+## What you do NOT do
+
+- Do not propose code rewrites — report findings only.
+- Do not run formatters or modify files.
+- Do not flag style in upstream files (Boy Scout suspended).
+- Do not reference Spring Boot, JPA, or Maven idioms — they do not apply here.
diff --git a/.claude/agents/react-reviewer.md b/.claude/agents/react-reviewer.md
new file mode 100644
index 00000000000..e680b36c7a0
--- /dev/null
+++ b/.claude/agents/react-reviewer.md
@@ -0,0 +1,140 @@
+---
+name: react-reviewer
+description: Expert React 16.8 + Redux + JavaScript code reviewer for the OpenBoxes frontend. Reviews components, hooks, Redux logic, forms, tests, and custom-package isolation. MUST BE USED for any changes under src/js/.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a senior React engineer reviewing OpenBoxes frontend code. The project is **React 16.8 + Redux + Webpack 5 + Node 14 + JavaScript (no TypeScript)**. You do NOT refactor or rewrite code — you report findings only.
+
+## Before Reviewing
+
+1. Establish scope:
+   - For PR review, use `gh pr view --json baseRefName` if available; otherwise use `git diff --staged` + `git diff`.
+   - For local review, prefer `git diff -- 'src/js/**'`.
+   - If the diff touches `src/js/` but no files are staged, fall back to `git show --patch HEAD -- 'src/js/**'`.
+2. Run the project checks:
+   - `npm run eslint` — report failures, stop if critical.
+   - `npm test -- --findRelatedTests <changed files>` — confirm tests still pass for the changed area.
+3. If the diff contains only changes outside `src/js/`, stop and defer to another reviewer (java-reviewer for backend).
+
+## Review Priorities
+
+### CRITICAL — Custom Package Isolation
+- **New files under `src/js/` (not `src/js/custom/`)** — flag as a high-severity violation of `rules/custom-package-isolation.md`. New code MUST live under `src/js/custom/<feature>/` unless it's a surgical fix to existing upstream code.
+- **Edits to upstream files outside `custom/`** — flag if the edit is non-minimal (reformatting, unrelated refactors, import reordering). Only surgical, functional edits are allowed.
+- **New dependencies** added to `package.json` — every new dep is a supply-chain surface and a merge-conflict source. Require justification.
+
+### CRITICAL — Security
+- **`dangerouslySetInnerHTML`** with unsanitized input → XSS
+- **`react-html-parser`** on user-supplied HTML without sanitization → XSS
+- **Bare `fetch` or `axios`** instead of the shared `apiClient` → bypasses CSRF and auth interceptors
+- **Secrets in `src/js/`** (API keys, tokens, connection strings)
+- **Open redirects** — `window.location = params.redirect` without allowlist validation
+- **PII in Redux state that's `redux-persist`'d** → ends up in localStorage
+
+### HIGH — React Correctness
+- **Missing `useEffect` dependencies** (should be flagged by `eslint-plugin-react-hooks`)
+- **Mutating Redux state** in reducers (`state.items.push`, `state.map = ...`)
+- **Mutating props or state** in components
+- **`setState` inside `useEffect` without a guard** → infinite loop
+- **`useEffect` for derived state** → should be computed at render or via `useMemo`
+- **`key={index}`** in dynamic lists with reordering
+- **Class components creating new objects in `render()`** passed to memoized children → defeats memoization
+- **Hooks called conditionally** or inside loops → violates rules of hooks
+- **Missing cleanup in `useEffect`** when it sets timers, subscriptions, or in-flight fetches
+
+### HIGH — Redux Patterns
+- **Thunks that don't dispatch `_REQUEST` / `_SUCCESS` / `_FAILURE`** actions — breaks the loading/error UI convention
+- **Reducers mutating state** — even with `immutability-helper`, bare mutation is wrong
+- **Selectors creating new references on every call** (returning `[]` literal, `{}` literal) — breaks `connect` shallow equality
+- **Duplicate server state in local `useState`** — source of drift bugs
+- **Wiring a new reducer into `redux-persist` whitelist** without reviewing privacy implications
+
+### HIGH — Forms
+- **Mixing `react-final-form` and `react-hook-form`** in the same wizard or form
+- **Inline validators in JSX** — should be extracted to `utils/` or feature-level validators file
+- **`react-hook-form` without a `zod` schema** for new forms — loses type-level validation
+- **Field arrays with > 100 rows** without virtualization or chunking — perf footgun
+- **Form submission not disabled while in-flight** → double-submission
+
+### HIGH — Idiomatic JS / Node 14
+- **`var` declarations** in new code → use `const` / `let`
+- **Optional chaining (`?.`) or nullish coalescing (`??`) in `webpack.config.js`** → runs on Node 14 without Babel, will crash
+- **`==` vs `===`** → always use strict equality
+- **`console.log`** left in committed code → use Sentry
+- **`moment`** in new date code → use `date-fns` v4
+- **`jquery`** in React components → only legacy GSP, never in React
+
+### MEDIUM — Performance
+- **Full-library lodash imports** (`import _ from 'lodash'`) → named imports
+- **Inline functions / objects as props to memoized children** → hoist or `useCallback`/`useMemo`
+- **N+1 API calls inside `.map()`** → batch
+- **Lists > 100 rows without virtualization**
+- **`react-final-form` without `<FormSpy subscription>`** for isolated re-renders on large forms
+
+### MEDIUM — Test Quality
+- **Assertions using `toBeDefined` / `toBeTruthy`** when a concrete value is knowable
+- **Tests not grouped in `describe` blocks**
+- **`data-testid` queries** when role/label/text would work
+- **`enzyme` usage** → not in deps; use RTL
+- **Mocking `axios` directly** instead of the shared `apiClient`
+- **Missing `act()` wrap** causing warnings in test output
+- **Snapshot tests on non-trivial components**
+
+### MEDIUM — i18n and Accessibility
+- **Hardcoded English strings in JSX** → must use `react-localize-redux`
+- **Icon-only buttons without `aria-label`**
+- **Non-semantic HTML** (`<div onClick>` instead of `<button>`)
+- **Form inputs without `<label>`** or `aria-labelledby`
+- **Missing `alt` on meaningful images**
+
+### MEDIUM — Code Style
+- **Non-PascalCase component names**
+- **Missing prop destructuring** at the top of the component body
+- **Import order violations** (should follow `eslint-plugin-simple-import-sort`)
+- **Inline styles** instead of SCSS/Bootstrap classes
+- **Magic numbers / strings** without named constants
+- **Mixed `.js` and `.jsx` extensions** inconsistent with neighbors
+
+## Diagnostic Commands
+
+```bash
+npm run eslint                                    # lint
+npm test -- --findRelatedTests <files>            # related tests
+npm run bundle                                    # production build (slow; only on request)
+git diff --stat -- 'src/js/**'                    # scope
+grep -rn "dangerouslySetInnerHTML" src/js/custom/ # XSS hunt
+grep -rn "console\.log" src/js/custom/            # stray logs
+grep -rn "import _ from 'lodash'" src/js/         # full-library imports
+grep -rn "data-testid" src/js/custom/             # test ID overuse
+```
+
+## Output Format
+
+```
+REACT REVIEW
+============
+Scope:     <files changed>
+ESLint:    [PASS/FAIL]
+Tests:     [PASS/FAIL/SKIPPED]
+
+CRITICAL:
+  - <finding> (file:line)
+
+HIGH:
+  - <finding> (file:line)
+
+MEDIUM:
+  - <finding> (file:line)
+
+Overall:   [APPROVE / WARNING / BLOCK]
+```
+
+## Approval Criteria
+
+- **Approve**: no CRITICAL or HIGH issues
+- **Warning**: MEDIUM issues only
+- **Block**: any CRITICAL (custom-package isolation, security) or HIGH issue
+
+Review with the mindset: "Would this code pass review at a React shop that ships a data-heavy admin app to real users?"
diff --git a/.claude/commands/gradle-build.md b/.claude/commands/gradle-build.md
new file mode 100644
index 00000000000..9c1e7e1cab0
--- /dev/null
+++ b/.claude/commands/gradle-build.md
@@ -0,0 +1,74 @@
+---
+description: Run and troubleshoot Gradle builds for the OpenBoxes Grails 3.3.16 project (JDK 8, Gradle 4.10.3). Delegates deeper diagnosis to the java-build-resolver agent.
+---
+
+# /gradle-build — OpenBoxes Grails build runbook
+
+## Step 1: Verify environment
+
+```bash
+java -version          # MUST be 1.8.x — anything newer breaks gradle-git-properties + Gradle 4.10.3
+./gradlew --version    # should report Gradle 4.10.3
+```
+
+If JDK is wrong, fix it first:
+
+```bash
+# user-global JDK pin (does not touch any repo file)
+mkdir -p ~/.gradle
+echo "org.gradle.java.home=/usr/lib/jvm/java-8-openjdk-amd64" >> ~/.gradle/gradle.properties
+```
+
+## Step 2: Pick the task
+
+| What you want | Command |
+|---|---|
+| Compile Java helpers | `./gradlew compileJava` |
+| Compile Groovy/Grails | `./gradlew compileGroovy` |
+| Run unit tests (Spock) | `./gradlew test` |
+| Run integration tests (`@Integration`) | `./gradlew integrationTest` |
+| Run the app (dev) | `./gradlew bootRun` |
+| Build the WAR | `./gradlew war` |
+| Stage Docker build context | `./gradlew prepareDocker -Dgrails.env=prod` |
+| Full assemble | `./gradlew assemble` |
+| Inspect dependencies | `./gradlew dependencies --configuration runtime` |
+| Why is this dependency on the classpath? | `./gradlew dependencyInsight --dependency <name> --configuration runtime` |
+| Clean | `./gradlew clean` |
+| Force re-resolve | `./gradlew --refresh-dependencies` |
+
+Add `--console=plain` if you see jansi / `JansiLoader` errors. Add `--info` for verbose progress.
+
+## Step 3: Frontend assets (when bundling for prod)
+
+`prepareDocker` and `war` trigger the webpack build. The frontend `package.json` is at the **repo root** (not under `src/main/webapp/`), and the stack is **Node 14 + npm 6–7** — anything newer is unsupported.
+
+```bash
+node -v                # must be 14.x
+npm install            # from repo root
+npm run build          # production webpack build
+npm run watch          # dev — rebuilds on change
+```
+
+If `prepareDocker` fails inside webpack, run the frontend build standalone first to see the real error.
+
+## Step 4: When something fails
+
+Hand the error to the `java-build-resolver` agent:
+
+> The build agent already knows the stack constraints (JDK 8, Gradle 4.10.3, Grails 3.3.16, Groovy 2.4, Node 14), the most common Grails build errors, and the fork's upstream-isolation rules. Paste the failing task name and the last ~50 lines of output and let it triage.
+
+## Step 5: Don't touch upstream build files
+
+`build.gradle`, `gradle.properties`, `settings.gradle`, `gradle/wrapper/gradle-wrapper.properties` are **upstream-owned**. Edits cause future merge conflicts. Prefer:
+
+1. `~/.gradle/gradle.properties` for user-global settings (JDK pin, proxy).
+2. A new file in `gradle/init.d/` for project-scoped init scripts.
+3. External config / env vars over `application.groovy` edits.
+
+If you genuinely must edit an upstream build file, keep the change one or two lines and document it in the matching OpenSpec change's `design.md` under "Upstream touch points".
+
+## Reference
+
+- Stack constraints, error tables, and Grails-specific gotchas: `.claude/agents/java-build-resolver.md`
+- Upstream-isolation rule (always applies): `.claude/rules/custom-package-isolation.md`
+- Fork-merge recipes: `.claude/docs/FORK_MAINTENANCE.md`
diff --git a/.claude/commands/verify.md b/.claude/commands/verify.md
new file mode 100644
index 00000000000..fdb1a9d4290
--- /dev/null
+++ b/.claude/commands/verify.md
@@ -0,0 +1,96 @@
+---
+description: Project-level verification runbook for the OpenBoxes EST fork — compile, test, lint, and custom-path isolation checks against the real stack (Grails 3.3.16 / JDK 8 / Node 14).
+---
+
+# /verify — OpenBoxes pre-commit verification
+
+This is the **project-local** `/verify` runbook. Run it before committing or opening a PR. It **replaces** the generic global `verify` skill, which doesn't know about our Grails / Groovy / Node 14 stack.
+
+The real project scripts are defined in `package.json` and `build.gradle`. Do not invent new tasks — the ones below are the ones that actually exist.
+
+## Step 1 — Backend compile (fast smoke test)
+
+This is the single highest-signal check. It catches most bad edits in seconds to a minute.
+
+```bash
+./gradlew compileGroovy
+```
+
+- Must succeed before proceeding. If it fails, hand the error to the `java-build-resolver` agent.
+- Also compiles `src/main/java/` helpers first (compileJava runs in the dependency chain).
+
+## Step 2 — Backend unit tests (Spock specs)
+
+```bash
+./gradlew test
+```
+
+Runs the Spock unit specs under `src/test/groovy/`. For new code this is a blocker — all new specs should land under `src/test/groovy/org/pih/warehouse/custom/<feature>/`.
+
+## Step 3 — Backend integration tests (slow, authoritative)
+
+```bash
+./gradlew integrationTest
+```
+
+Runs the `@Integration` specs under `src/integration-test/groovy/` with a real Grails context. Much slower than `test` — skip during inner-loop iteration, but **do not skip before PR**. It's the only layer that catches GORM / transactional / Liquibase wiring bugs.
+
+## Step 4 — Frontend lint
+
+```bash
+npm run eslint
+```
+
+> The `package.json` script is named **`eslint`**, not `lint` — `npm run eslint` runs `eslint --fix --ext .js,.jsx ./src/js/`.
+
+## Step 5 — Frontend tests
+
+```bash
+npm test
+```
+
+Runs Jest + @testing-library/react. Required for any change under `src/js/`.
+
+## Step 6 — Custom-path isolation check
+
+Every **newly added** `.groovy`, `.java`, `.jsx`, `.js`, `.scss` file must live under a `custom/` path — see `rules/custom-package-isolation.md`.
+
+> **⚠️ Pick the base ref first.** EST feature branches are typically based on `release/est/<version>`, not `develop`. If you don't set `VERIFY_BASE`, the default `origin/develop` is likely wrong for your branch and you'll see false positives (files from the EST release branch that aren't "new" to your feature). Run `git merge-base HEAD origin/develop origin/release/est/*` to find the right base, then export it.
+
+```bash
+# Set this to the ref your feature branched FROM, not the ref you'll merge INTO:
+export VERIFY_BASE="${VERIFY_BASE:-origin/release/est/0.9.7}"   # current release branch
+# export VERIFY_BASE=origin/develop                              # only if you branched from develop
+
+git fetch origin "${VERIFY_BASE#origin/}" 2>/dev/null || true
+
+git diff --name-only --diff-filter=A "${VERIFY_BASE}...HEAD" -- \
+    grails-app/ src/main/groovy/ src/main/java/ src/js/ \
+    src/test/groovy/ src/integration-test/groovy/ \
+  | grep -E '\.(groovy|java|js|jsx|scss)$' \
+  | grep -vE '(^|/)custom/' \
+  || echo "OK: all newly added source files are under custom/"
+```
+
+- Any output from the final `grep -vE` stage is a **blocker** — re-route the file to a `custom/` path (see `rules/custom-package-isolation.md` for the layer → path table).
+- Migrations under `grails-app/migrations/` must specifically be under `grails-app/migrations/custom/`; the pipeline above catches that too.
+- Simpler top-level pathspecs (`grails-app/`, `src/js/`, …) are used instead of `**` globs because git's default pathspec handling does not expand `**` unless `--glob-pathspecs` is set — the extension filter in the next stage does the narrowing.
+
+## Step 7 — Pre-Commit Self-Review (manual)
+
+Open `CLAUDE.md` (repo root) and walk the **Pre-Commit Self-Review — Project-Specific** and team-wide checklists. They cover upstream-compatibility isolation, Grails layering, Groovy idioms, language floors, `@Autowired` absence, raw-SQL justification, and the Boy Scout exemption — the things an automated check can't verify for you.
+
+## When a step fails
+
+| Step | Failing — who to ask |
+|---|---|
+| `compileGroovy` / `test` / `integrationTest` | `java-build-resolver` agent for errors, `java-reviewer` agent for code quality. |
+| `npm run eslint` / `npm test` | `react-reviewer` agent. |
+| Custom-path isolation | Move the file under `custom/`. No agent — it's a hard rule (`rules/custom-package-isolation.md`). |
+
+## Reference
+
+- Stack / command details: `.claude/commands/gradle-build.md`
+- Upstream-isolation rule: `.claude/rules/custom-package-isolation.md`
+- Backend review criteria: `.claude/agents/java-reviewer.md`
+- Frontend review criteria: `.claude/agents/react-reviewer.md`
diff --git a/.claude/docs/FORK_MAINTENANCE.md b/.claude/docs/FORK_MAINTENANCE.md
new file mode 100644
index 00000000000..63d5745f6e3
--- /dev/null
+++ b/.claude/docs/FORK_MAINTENANCE.md
@@ -0,0 +1,262 @@
+# Fork Maintenance — Command Recipes
+
+Concrete git command walkthroughs for maintaining the OpenBoxes fork. **The rules and policy live in `CLAUDE.md` (Fork Maintenance & Branching section)** — this doc is just the "how do I actually run the commands" companion. Read the policy first; reach for this when you need a recipe.
+
+Branch naming reminder:
+- `develop` — upstream-only mirror. Never a source of our customer work.
+- `release/<version>` — upstream release mirrors (e.g. `release/0.9.6-hotfix1`, `release/0.9.8`). Upstream-pristine.
+- `release/<client>/<version>` — per-client customization branch (e.g. `release/spocc/0.9.6-hotfix1`). Built on top of the matching upstream release.
+- `feature/<client>-<name>` / `fix/<client>-<name>` — short-lived, branch from and merge back to `release/<client>/<version>`.
+
+---
+
+## Recipe 0 — One-time setup: `git rerere`
+
+Enable globally so recurring merge conflicts resolve themselves on repeated replays:
+
+```bash
+git config --global rerere.enabled true
+```
+
+Do this once per developer machine. You never have to think about it again.
+
+---
+
+## Recipe 1 — Create a new customer customization branch
+
+Use this when you're standing up a new customer for the first time (e.g. adding SPOCC, or later adding Tajikistan).
+
+```bash
+git fetch origin
+git checkout release/0.9.6-hotfix1          # or whichever upstream baseline
+git pull
+git checkout -b release/spocc/0.9.6-hotfix1
+git push -u origin release/spocc/0.9.6-hotfix1
+```
+
+For a second customer:
+
+```bash
+git checkout release/0.9.6-hotfix1           # same upstream baseline (or different, up to you)
+git checkout -b release/tjk-lmis/0.9.6-hotfix1
+git push -u origin release/tjk-lmis/0.9.6-hotfix1
+```
+
+Two independent customization branches. No shared customer code between them.
+
+---
+
+## Recipe 2 — Start a feature branch for customer work
+
+```bash
+git checkout release/spocc/0.9.6-hotfix1
+git pull
+git checkout -b feature/spocc-season-entity
+# ...do the work, commit
+git push -u origin feature/spocc-season-entity
+# open a PR targeting release/spocc/0.9.6-hotfix1 (NOT develop, NOT main)
+```
+
+**Target the right branch when opening the PR.** GitHub defaults to the repo's default branch, which is usually `develop`. Change it to `release/spocc/0.9.6-hotfix1` explicitly. Getting this wrong is the #1 way customer code leaks into `develop`.
+
+When the PR merges:
+- Squashing is allowed on `release/<client>/<version>`, not on `develop`. See the squashing section in `CLAUDE.md`.
+- Preserve any `(cherry picked from commit X)` trailers in the squash commit body.
+
+---
+
+## Recipe 3 — Upstream version bump via `cherry-pick` (recommended)
+
+Scenario: upstream just tagged `release/0.9.8`. Brad's instance is running off `release/spocc/0.9.6-hotfix1`. You want to move it to 0.9.8.
+
+```bash
+# 1. Fetch the new upstream release
+git fetch origin
+git checkout release/0.9.8             # upstream-pristine mirror. Create from upstream if missing.
+git pull
+
+# 2. Create the new custom branch from the new upstream baseline
+git checkout -b release/spocc/0.9.8
+
+# 3. Replay the custom layer onto it.
+#    The A..B range means "commits reachable from B but not from A" —
+#    i.e. exactly your custom commits, nothing from the old upstream.
+git cherry-pick release/0.9.6-hotfix1..release/spocc/0.9.6-hotfix1
+
+# 4. Conflicts will surface — see Recipe 5 for the playbook.
+#    For each conflict:
+#      edit file → git add <file> → git cherry-pick --continue
+#    To skip a commit that upstream has already absorbed:
+#      git cherry-pick --skip
+#    To bail out entirely and try a different approach:
+#      git cherry-pick --abort
+
+# 5. Build + test
+./gradlew clean build
+./gradlew test
+npm test
+cd docker && docker-compose up -d
+# manually smoke-test the IMS workflows
+
+# 6. Push
+git checkout release/spocc/0.9.8
+git push -u origin release/spocc/0.9.8
+
+# 7. Deploy: staging first, bake, then cut prod over.
+#    Leave release/spocc/0.9.6-hotfix1 alone until 0.9.8 has proven itself in prod.
+#    It is your rollback branch.
+```
+
+### What the `A..B` range actually picks up
+
+```
+upstream 0.9.6-hotfix1  ●━●━●━●                              ← release/0.9.6-hotfix1
+                                ╲
+                                 ●━●━●━●                     ← release/spocc/0.9.6-hotfix1
+                                 ^^^^^^^ these 4 commits are A..B
+
+upstream 0.9.8  ●━●━●━●━●━●━●                                ← release/0.9.8
+                              ╲
+                               ●━●━●━●                       ← release/spocc/0.9.8 (after replay)
+                               the same 4 custom commits, replayed on the new baseline
+```
+
+---
+
+## Recipe 4 — Upstream version bump via `rebase --onto` (alternative)
+
+Same result as Recipe 3, different command shape. Pick whichever reads more naturally. Both trigger `rerere` identically.
+
+```bash
+git fetch origin
+git checkout -b release/spocc/0.9.8 release/spocc/0.9.6-hotfix1
+git rebase --onto release/0.9.8 release/0.9.6-hotfix1
+```
+
+Read as: "Take the commits on the current branch that aren't in `release/0.9.6-hotfix1`, and replay them onto `release/0.9.8`." Same custom-layer replay, expressed as a rebase instead of a range cherry-pick.
+
+**Heads up:** rebase rewrites commit hashes. If the old branch had commits shared with another branch (e.g. a feature branch not yet merged), coordinate before rebasing. Cherry-pick (Recipe 3) doesn't have this concern since it creates fresh commits on a new branch without touching the old one.
+
+---
+
+## Recipe 5 — Conflict resolution playbook
+
+Conflicts during a version bump come from two places, roughly in order of likelihood:
+
+### 5a. Upstream touched files your customization also touched
+
+This is exactly what Upstream Compatibility rule 7 exists for. Each OpenSpec archived change must list its upstream touch points in `design.md`. Before you start the cherry-pick, grep for them:
+
+```bash
+grep -r "Upstream touch points" openspec/changes/archive/
+```
+
+That gives you the hotspot list. Eyeball each file to see whether upstream changed it between 0.9.6-hotfix1 and 0.9.8:
+
+```bash
+git log release/0.9.6-hotfix1..release/0.9.8 -- path/to/touched/file
+```
+
+If upstream touched it, expect a conflict on that file during the replay. If they didn't, it'll replay clean.
+
+### 5b. Liquibase changelog include order
+
+If upstream added new migrations to `grails-app/migrations/changelog.groovy`, your custom `include` directive may end up in a different relative position. The fix is always the same: **keep the custom include *at the end*** of `changelog.groovy`. During conflict resolution, accept upstream's new include lines and move your custom include below them.
+
+Per Upstream Compatibility rule 5, your migrations are additive and live in their own file/folder, so the actual changeset contents never conflict — only the registration order.
+
+### 5c. `custom/*` code conflicting
+
+If a file under `org.pih.warehouse.custom.*` or `src/js/custom/*` shows a conflict, **stop and investigate**. Code-level isolation means these files shouldn't exist upstream and therefore can't conflict. If one does, either:
+- Someone accidentally committed customer code outside a `custom/*` path (audit the prior PR), or
+- You're on the wrong base branch (check `git log --oneline -5`), or
+- An upstream merge to your custom branch re-introduced an upstream path that collides with your custom path by coincidence (rare).
+
+Investigate before resolving.
+
+### 5d. Generic conflict resolution commands
+
+```bash
+# See what's conflicted
+git status
+
+# After editing a file to resolve:
+git add <file>
+
+# Continue the cherry-pick / rebase:
+git cherry-pick --continue    # or git rebase --continue
+
+# Skip the current commit (upstream already has equivalent changes):
+git cherry-pick --skip        # or git rebase --skip
+
+# Abort everything and go back to where you were:
+git cherry-pick --abort       # or git rebase --abort
+```
+
+`git rerere` (Recipe 0) silently records every conflict resolution and auto-applies it on the next replay, which matters when you do a version bump twice (e.g. staging first, prod later, or a retry after a build failure).
+
+---
+
+## Recipe 6 — Rollback after a bad version bump
+
+You cut `release/spocc/0.9.8` over to prod. It broke. You need to get Brad back on 0.9.6-hotfix1.
+
+```bash
+# On the deployment side: redeploy from the old branch
+git checkout release/spocc/0.9.6-hotfix1
+# rebuild + redeploy the Docker image
+cd docker && docker-compose build && docker-compose up -d
+
+# On the repo side: leave the old branch alone. Investigate what broke on 0.9.8,
+# fix it on release/spocc/0.9.8 (or start over with a new branch if rebase is cleaner),
+# and try again.
+```
+
+**Do not delete `release/spocc/0.9.6-hotfix1` until the new version has baked in prod for a meaningful period.** Days at minimum, a full gift-box season ideally. Old branches are cheap; lost prod data is expensive.
+
+If you want to mark the old tip as "this was prod at time T" before eventually deleting, tag it:
+
+```bash
+git tag release/spocc/0.9.6-hotfix1-pre-0.9.8-cutover release/spocc/0.9.6-hotfix1
+git push origin release/spocc/0.9.6-hotfix1-pre-0.9.8-cutover
+```
+
+Tags are lightweight and survive branch deletion.
+
+---
+
+## Recipe 7 — Auditing "what's custom on this instance?"
+
+Two methods; run both and cross-check.
+
+### 7a. By git diff (the mechanical truth)
+
+```bash
+git diff release/0.9.6-hotfix1..release/spocc/0.9.6-hotfix1 --stat
+```
+
+That's the literal list of files changed by your custom layer. `--stat` gives you the summary; drop it for the full diff.
+
+### 7b. By OpenSpec archive (the narrative truth)
+
+```bash
+ls openspec/changes/archive/
+```
+
+Each archived change is one customer-facing feature. Cross-reference the two — anything in the git diff that isn't represented by an archived change is either a trivial commit that didn't warrant a proposal (seed data, config tweaks) or a process leak to investigate.
+
+---
+
+## Quick reference
+
+| I want to... | Recipe |
+|---|---|
+| Enable `git rerere` | 0 |
+| Create `release/spocc/0.9.6-hotfix1` for the first time | 1 |
+| Add `release/tjk-lmis/0.9.6-hotfix1` as a second customer | 1 |
+| Start a new feature branch for SPOCC | 2 |
+| Bump SPOCC from 0.9.6 to 0.9.8 via cherry-pick | 3 |
+| Bump via `rebase --onto` instead | 4 |
+| Resolve conflicts during a bump | 5 |
+| Roll prod back to the previous baseline | 6 |
+| Audit what's custom on an instance | 7 |
diff --git a/.claude/hooks/enforce-custom-path.sh b/.claude/hooks/enforce-custom-path.sh
new file mode 100755
index 00000000000..83216ab0119
--- /dev/null
+++ b/.claude/hooks/enforce-custom-path.sh
@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# PreToolUse hook — enforces the custom-path isolation rule for new files.
+#
+# Fires on Write only (not Edit). Blocks the write when a NEW source file
+# is being created outside a custom/ folder. Existing upstream files (already
+# tracked by git) are always allowed through because Write may be used to
+# overwrite them.
+#
+# See .claude/rules/custom-package-isolation.md for the full rule.
+#
+# Exit codes:
+#   0  — allow (not a matching path, or under custom/, or already tracked)
+#   2  — block (stderr message is shown to the model)
+
+set -euo pipefail
+
+# Read the tool input JSON from stdin.
+input="$(cat)"
+
+# Extract the target path. Without jq we do a minimal grep; jq is preferred.
+if command -v jq >/dev/null 2>&1; then
+    file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')"
+else
+    file_path="$(printf '%s' "$input" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+fi
+
+if [ -z "${file_path:-}" ]; then
+    exit 0
+fi
+
+# Normalize to a repo-relative path.
+# CLAUDE_PROJECT_DIR is set by the harness; fall back to PWD.
+repo_root="${CLAUDE_PROJECT_DIR:-$PWD}"
+case "$file_path" in
+    /*) rel="${file_path#$repo_root/}" ;;
+    *)  rel="$file_path" ;;
+esac
+
+# Only enforce inside the tracked source trees, and only on source-like
+# extensions. Uses bash regex so arbitrary nesting depth works.
+if [[ "$rel" =~ ^grails-app/migrations/.*\.groovy$ ]]; then
+    migration_file=1
+elif [[ "$rel" =~ ^grails-app/.*\.(groovy|java)$ ]]; then
+    migration_file=0
+elif [[ "$rel" =~ ^src/main/(groovy|java)/.*\.(groovy|java)$ ]]; then
+    migration_file=0
+elif [[ "$rel" =~ ^src/js/.*\.(js|jsx|scss)$ ]]; then
+    migration_file=0
+else
+    # Not a source file we care about — allow.
+    exit 0
+fi
+
+# If the file is already tracked by git, this is an edit to an existing
+# upstream file — allowed (Edit would be preferred, but we don't block Write
+# on tracked files because overwrites are sometimes legitimate).
+if git -C "$repo_root" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+    exit 0
+fi
+
+# From here on, this is a NEW file.
+
+# Migrations: must live under grails-app/migrations/custom/
+if [ "${migration_file:-0}" = "1" ]; then
+    case "$rel" in
+        grails-app/migrations/custom/*) exit 0 ;;
+    esac
+    cat >&2 <<EOF
+BLOCKED by .claude/hooks/enforce-custom-path.sh:
+  New Liquibase migration must live under grails-app/migrations/custom/.
+  Rejected path: $rel
+  Expected:      grails-app/migrations/custom/$(date +%Y-%m-%d)-<feature>.groovy
+  See .claude/rules/custom-package-isolation.md (custom-package isolation rule)
+  and wire it into grails-app/migrations/custom/changelog.groovy.
+EOF
+    exit 2
+fi
+
+# All other source files: path must contain a /custom/ segment
+# (equivalent to org.pih.warehouse.custom.* for Java/Groovy package trees).
+case "/$rel/" in
+    */custom/*) exit 0 ;;
+esac
+
+# Block.
+cat >&2 <<EOF
+BLOCKED by .claude/hooks/enforce-custom-path.sh:
+  New source files must live under a custom/ path so upstream merges stay clean.
+  Rejected path: $rel
+
+  Re-route to one of:
+    grails-app/{services,controllers,domain,taglib,jobs}/org/pih/warehouse/custom/<feature>/...
+    src/main/groovy/org/pih/warehouse/custom/<feature>/...
+    src/main/java/org/pih/warehouse/custom/<feature>/...
+    src/js/custom/<feature>/{components,hooks,utils,redux,__tests__}/...
+
+  See .claude/rules/custom-package-isolation.md for the full layer -> path table.
+  (This hook only fires on Write; editing an existing upstream file via Edit is allowed.)
+EOF
+exit 2
diff --git a/.claude/rules/custom-package-isolation.md b/.claude/rules/custom-package-isolation.md
new file mode 100644
index 00000000000..0e01d31de25
--- /dev/null
+++ b/.claude/rules/custom-package-isolation.md
@@ -0,0 +1,144 @@
+---
+paths:
+  - "grails-app/**"
+  - "src/main/**"
+  - "src/main/groovy/**"
+  - "src/main/java/**"
+  - "src/main/webapp/**"
+  - "src/test/**"
+  - "src/integration-test/**"
+  - "src/js/**"
+  - "test/**"
+---
+
+# Custom Package Isolation (CRITICAL)
+
+> This is the **single most important rule** in this fork. Every new custom line of code MUST live under a `custom/` subfolder or `org.pih.warehouse.custom.*` package. Failure to do this creates merge conflicts forever when we pull upstream updates, because any file we edited becomes a conflict point when upstream also edits it.
+
+## The Rule
+
+**All new code goes under a `custom` path.** Period.
+
+| Layer | Where new files go |
+|---|---|
+| Grails domain classes | `grails-app/domain/org/pih/warehouse/custom/<feature>/` |
+| Grails services | `grails-app/services/org/pih/warehouse/custom/<feature>/` |
+| Grails controllers | `grails-app/controllers/org/pih/warehouse/custom/<feature>/` |
+| Grails views (GSP) | `grails-app/views/custom/<feature>/` |
+| Grails taglibs | `grails-app/taglib/org/pih/warehouse/custom/<feature>/` |
+| Grails interceptors | `grails-app/controllers/org/pih/warehouse/custom/<feature>/` |
+| Grails commands / jobs | `grails-app/jobs/org/pih/warehouse/custom/<feature>/` |
+| Liquibase migrations | `grails-app/migrations/custom/` (filename prefixed with date + feature) |
+| i18n messages | `grails-app/i18n/custom/<feature>-messages_<locale>.properties` (if separated from upstream) |
+| Java helpers | `src/main/java/org/pih/warehouse/custom/<feature>/` |
+| Groovy helpers | `src/main/groovy/org/pih/warehouse/custom/<feature>/` |
+| React components | `src/js/custom/<feature>/components/` |
+| React hooks | `src/js/custom/<feature>/hooks/` |
+| React utils | `src/js/custom/<feature>/utils/` |
+| Redux actions / reducers / selectors | `src/js/custom/<feature>/redux/` |
+| Frontend tests | `src/js/custom/<feature>/__tests__/` |
+| Backend unit tests | `src/test/groovy/org/pih/warehouse/custom/<feature>/` |
+| Backend integration tests | `src/integration-test/groovy/org/pih/warehouse/custom/<feature>/` |
+
+**`<feature>` is a short kebab-case or camelCase name** describing the feature: `gs1-barcode`, `ims-migration`, `seasonCartonCascade`, etc. Match the convention already in use within the custom folder.
+
+## Why
+
+OpenBoxes is a **fork** of upstream PIH OpenBoxes. We pull upstream updates periodically — every merge replays upstream commits onto our EST layer, and onto every customer branch on top of EST. The number of merge conflicts is proportional to the number of upstream files we've touched. If every custom line lives in a `custom/` folder that upstream never touches, we get **zero conflicts** on those files.
+
+**The corollary:** the Boy Scout Rule from the global CLAUDE.md is **suspended** for any file outside the custom folders. Do not reformat, reorder imports, rename symbols, or "clean up" upstream files. Every incidental edit is a future merge conflict for zero functional benefit.
+
+## When You MUST Touch an Upstream File
+
+Sometimes a feature genuinely requires modifying an existing upstream file (adding a menu link, registering a new controller, hooking into an existing wizard step). The rules are:
+
+1. **Keep the edit surgical and localized.** Change only the lines the feature requires. No incidental cleanup, no import reordering, no rename-while-you're-there.
+2. **Prefer extension points** — Grails service injection, event listeners, taglib additions, React component composition via props/children — over rewriting the upstream logic.
+3. **Document the touch point.** Every OpenSpec change (`openspec/changes/<change>/design.md`) MUST include an "Upstream touch points" section listing the upstream files modified and the one-line reason for each. This is our merge-conflict hitlist for future upstream pulls.
+4. **Prefer a new file + a one-line include** over editing a big file. Example: instead of inlining a new section into `grails-app/views/dashboard/index.gsp`, create `grails-app/views/custom/<feature>/_section.gsp` and add a single `<g:render template="/custom/<feature>/section"/>` line to `index.gsp`.
+
+## When You're Creating a New File
+
+**Before you write the first line, check the destination path.** If the path does not contain `custom/` or `org.pih.warehouse.custom.*`, STOP and re-route.
+
+### Backend example
+
+```
+❌ grails-app/services/org/pih/warehouse/inventory/IMSImportService.groovy
+✅ grails-app/services/org/pih/warehouse/custom/imsImport/IMSImportService.groovy
+```
+
+### Frontend example
+
+```
+❌ src/js/components/imsImport/ImsImportPage.jsx
+✅ src/js/custom/imsImport/components/ImsImportPage.jsx
+```
+
+### Migration example
+
+```
+❌ grails-app/migrations/0.9.x/add-ims-fields.groovy
+✅ grails-app/migrations/custom/2026-04-13-add-ims-fields.groovy
+```
+
+## Wiring It Up
+
+### Liquibase
+
+Add the custom changeset to the master changelog **via an include line**, not by inlining:
+
+```groovy
+// grails-app/migrations/changelog.groovy
+databaseChangeLog = {
+    // ... upstream includes unchanged ...
+    include file: 'custom/changelog.groovy'  // <-- add this ONE line
+}
+```
+
+Then `grails-app/migrations/custom/changelog.groovy` aggregates all custom migrations:
+
+```groovy
+databaseChangeLog = {
+    include file: '2026-04-13-add-ims-fields.groovy'
+    include file: '2026-04-15-ims-indexes.groovy'
+}
+```
+
+This minimizes upstream-file touches to one line.
+
+### Spring beans
+
+If a custom class needs to be registered as a Spring bean (rare; Grails auto-scans `grails-app/` subfolders), add it in `grails-app/conf/spring/resources.groovy`. That file is edited rarely by upstream, so diffs there have low conflict risk.
+
+### React routes
+
+If you're adding a new React route, the route table is in `src/js/routes/` (or wherever the project has it). That's an upstream file — the edit is a single `<Route>` line, which is acceptable and should be noted in the design.md touch points.
+
+## Boy Scout Rule
+
+The team-wide Boy Scout Rule from `~/.claude/est/CLAUDE.md` is **suspended inside any upstream file** (anything not under `custom/` or `org.pih.warehouse.custom.*`). Apply cleanups ONLY inside the custom folders.
+
+## Enforcement in Code Review
+
+The `code-review`, `java-reviewer`, and `react-reviewer` agents all check this rule. Any new file outside the custom folders is flagged as **CRITICAL** — a blocker, not a warning.
+
+## Starting a New Feature
+
+Start every non-trivial custom feature with `/opsx:propose` — it generates the OpenSpec change folder (`openspec/changes/<change>/`) with `proposal.md`, `design.md`, `tasks.md`, and the spec files. The `design.md` template must include an "Upstream touch points" section if the work modifies any upstream file.
+
+When you create the first real backend or frontend file for the feature, place it under the matching `custom/` path from the table above. There is no directory scaffolder — this rule file plus the reviewer agents are the enforcement.
+
+## FAQ
+
+**Q: What if the feature is tiny — one controller and one GSP? Do I still need the whole structure?**
+A: Yes. The path `grails-app/controllers/org/pih/warehouse/custom/<feature>/FooController.groovy` is not overhead — it's the difference between "upstream merge just works" and "upstream merge has conflicts".
+
+**Q: The existing OpenBoxes code doesn't follow this structure. Can I put my new file next to the existing code for consistency?**
+A: No. The existing code is upstream-pristine; our custom additions live in a parallel `custom/` structure. Consistency with upstream means **leaving upstream alone**, not adopting its layout for new files.
+
+**Q: What about tests for upstream code I had to edit?**
+A: Write the tests under `src/test/groovy/org/pih/warehouse/custom/<feature>/` even if the code under test is upstream. The test file is yours, so it lives in your tree.
+
+**Q: What if two customers share a custom feature?**
+A: Then it belongs on the EST shared layer (`release/est/<version>`), not the per-customer branch. The file layout is the same — `org.pih.warehouse.custom.<feature>/` — it's just pushed down the stack one level.
diff --git a/.claude/rules/groovy/patterns.md b/.claude/rules/groovy/patterns.md
new file mode 100644
index 00000000000..78fba285c15
--- /dev/null
+++ b/.claude/rules/groovy/patterns.md
@@ -0,0 +1,314 @@
+---
+paths:
+  - "grails-app/**/*.groovy"
+  - "src/main/groovy/**/*.groovy"
+  - "src/test/groovy/**/*.groovy"
+---
+
+# Grails / Groovy Patterns — OpenBoxes
+
+> **Stack:** Grails 3.3.16 on Spring Boot, Groovy 2.4.21, GORM / Hibernate 5.2.18, MySQL 8 / MariaDB 10.3, Liquibase (via Grails Database Migration plugin).
+
+## Language Floor: Groovy 2.4
+
+Groovy 2.4 is the last 2.x release and is **feature-frozen**. Do not use Groovy 3.0+ features:
+
+- **No method references** (`String::toUpperCase`) — use closures (`{ it.toUpperCase() }`)
+- **No `!in` / `!instanceof`** — use `!(x in y)` / `!(x instanceof Y)`
+- **No `final` as a method modifier with closures** — parser quirks
+- **No Groovy 3 type inference** (`var`) — declare types or use `def`
+
+Also: **OpenJDK 8** is the JVM. See `rules/java/patterns.md` for the forbidden Java features — they're also forbidden in `.groovy` code because they produce the same bytecode.
+
+## The Four Load-Bearing Grails Conventions
+
+If you only internalize four things, make it these:
+
+### 1. Services are transactional by default
+
+```groovy
+class OrderService {
+    // EVERY public method runs in a transaction automatically.
+    // This is a HUGE footgun for devs coming from Spring Boot.
+
+    Order place(OrderCommand cmd) {
+        // inside a transaction, even though there's no @Transactional
+    }
+}
+```
+
+- To **disable** transactions on a single method: `@NotTransactional` (rare; use only when you explicitly want it non-transactional).
+- To mark a service entirely **read-only**: `static transactional = false` at the class level, then annotate individual methods with `@Transactional(readOnly = true)` or `@Transactional` as needed.
+- To mark a single method **read-only**: `@Transactional(readOnly = true)`.
+- **Never sprinkle `@Transactional` everywhere** — Grails services already wrap you. Only use the annotation to override defaults (read-only, propagation, noRollbackFor).
+
+### 2. Dependency injection is property-based and convention-driven
+
+```groovy
+class OrderService {
+    // Just declare a property named after the bean — Grails wires it automatically.
+    def inventoryService
+    def productService
+    def grailsApplication   // access to config
+    def messageSource       // i18n
+    def springSecurityService  // current user, etc.
+}
+```
+
+- **No `@Autowired`, no `@Inject`, no constructor injection.**
+- **Typed `def` is OK too**: `InventoryService inventoryService` — same effect, better IDE support.
+- If a collaborator isn't in the Grails beans registry, register it in `grails-app/conf/spring/resources.groovy`.
+
+### 3. Domain classes use GORM mappings, not JPA
+
+```groovy
+class Product {
+    String name
+    String productCode
+    String description
+    Category category
+    BigDecimal pricePerUnit
+
+    static hasMany = [
+        synonyms: ProductSynonym,
+        attributes: ProductAttribute,
+    ]
+
+    static belongsTo = [category: Category]
+
+    static constraints = {
+        name blank: false, maxSize: 255
+        productCode blank: false, unique: true, maxSize: 100
+        description nullable: true, maxSize: 2000
+        pricePerUnit nullable: true, min: 0.0, scale: 4
+    }
+
+    static mapping = {
+        table 'product'
+        id generator: 'uuid'
+        version false
+        category fetch: 'join'
+    }
+}
+```
+
+- **No `@Entity`, `@Table`, `@Column`, `@Id`, `@OneToMany`** — GORM derives all of this from the class and `static mapping` / `static constraints` blocks.
+- **`static constraints`** replaces Bean Validation (`@NotNull`, `@NotBlank`, `@Size`).
+- **`static mapping`** replaces `@Table`, `@Column`, `@ManyToOne(fetch = ...)`, etc.
+- **`static hasMany` / `static belongsTo` / `static hasOne`** replace `@OneToMany` / `@ManyToOne` / `@OneToOne`.
+- **Domain package layout:** subdomains live in `grails-app/domain/org/pih/warehouse/<subdomain>/` (`core/`, `inventory/`, `order/`, `product/`, `shipping/`, `requisition/`, …). New custom domain classes go under `grails-app/domain/org/pih/warehouse/custom/<feature>/`.
+
+### 4. Controllers are thin and use Grails conventions
+
+```groovy
+class ProductController {
+    def productService
+
+    def show(Long id) {
+        Product product = Product.get(id)
+        if (!product) {
+            notFound()
+            return
+        }
+        respond product
+    }
+
+    def save(ProductCommand cmd) {
+        if (cmd.hasErrors()) {
+            respond cmd.errors, status: 400
+            return
+        }
+        Product product = productService.save(cmd)
+        respond product, status: 201
+    }
+}
+```
+
+- **Parameters come via `params`** (`params.id`, `params.name`) or via a command object with constraints.
+- **`respond`** picks the right renderer (JSON, XML, HTML) based on the `Accept` header. `render` is the lower-level primitive.
+- **Never put business logic in a controller.** Delegate to a service. Flag any controller method over ~15 lines.
+- **API controllers** under `grails-app/controllers/org/pih/warehouse/api/` typically extend `BaseDomainApiController` — check inheritance before duplicating generic CRUD logic.
+
+## GORM Query Decision Tree
+
+For any read operation, pick the lowest rung that works:
+
+1. **Dynamic finders** for simple single-field lookups:
+   ```groovy
+   Product.findByProductCode('ABC123')
+   Product.findAllByCategoryAndActive(cat, true)
+   Product.findByNameLike('%widget%')
+   ```
+2. **`where` queries** for type-safe multi-condition queries (Groovy DSL):
+   ```groovy
+   def results = Product.where {
+       category == cat && pricePerUnit > minPrice
+   }.list(max: 50, sort: 'name')
+   ```
+3. **Criteria queries** (`createCriteria()`) for complex dynamic filters:
+   ```groovy
+   def products = Product.createCriteria().list {
+       eq('category', cat)
+       between('pricePerUnit', min, max)
+       fetchMode 'synonyms', org.hibernate.FetchMode.JOIN
+       maxResults(50)
+       order('name', 'asc')
+   }
+   ```
+4. **HQL** via `Product.executeQuery(...)` for joins, projections, and aggregations that criteria can't express cleanly.
+5. **Raw SQL** via `groovy.sql.Sql` — last resort. Requires a comment explaining *why* and MUST be parameterized (no string concatenation).
+
+Escalate only when the lower rung can't express what you need.
+
+## The N+1 Trap
+
+Lazy loading is the default. A `.each { it.category.name }` across 1000 products fires 1000 queries. Defend with:
+
+- `fetchMode 'category', FetchMode.JOIN` in criteria
+- `Product.findAll("from Product p join fetch p.category")` in HQL
+- `static mapping { category fetch: 'join' }` on the domain class (caution: eager-by-default across the codebase)
+
+**Enable Hibernate SQL logging** in dev to catch N+1 early:
+```yaml
+logging:
+  level:
+    org.hibernate.SQL: DEBUG
+    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
+```
+
+## Constraints & Validation
+
+- Validation runs **on save**. `entity.validate()` triggers it without saving.
+- **Custom validators:**
+  ```groovy
+  static constraints = {
+      productCode validator: { value, obj ->
+          if (!value.startsWith('SKU-')) {
+              return 'productCode.invalidPrefix'   // i18n key
+          }
+      }
+  }
+  ```
+- Always define error messages as i18n keys in `grails-app/i18n/messages*.properties`, never hardcoded English.
+
+## Command Objects
+
+For complex controller inputs, use command objects instead of raw `params`:
+
+```groovy
+class CreateOrderCommand {
+    String customerName
+    Long locationId
+    List<OrderItemCommand> items
+
+    static constraints = {
+        customerName blank: false, maxSize: 255
+        locationId nullable: false
+        items nullable: false, minSize: 1
+    }
+}
+```
+
+Validation happens automatically when the command object is passed to an action.
+
+## Groovy Idioms (functional style)
+
+The codebase already uses `.collect`, `.findAll`, `.groupBy`, `.inject`, `.find`, `.any`, `.every` ~8.7× more often than imperative `for` loops. **Match that.**
+
+```groovy
+// GOOD — functional
+List<String> names = products.collect { it.name }
+List<Product> expensive = products.findAll { it.price > 100 }
+Map<Category, List<Product>> byCategory = products.groupBy { it.category }
+BigDecimal total = items.inject(BigDecimal.ZERO) { sum, item -> sum + item.total }
+Product featured = products.find { it.featured }
+
+// BAD — Java-style
+List<String> names = []
+for (Product p : products) {
+    names.add(p.name)
+}
+```
+
+- **No Java Streams** in Groovy (`.stream().map(...).collect(toList())`) — not idiomatic, and Groovy closures are simpler.
+- **`.with { }` and `.tap { }` are OK** but use sparingly; clarity beats cleverness.
+- **Null-safe navigation (`?.`), Elvis (`?:`), safe navigation indexing (`?[...]`)** — use freely.
+
+## Groovy Truth
+
+`if (thing) { ... }` is true when:
+- `thing` is not `null`
+- `thing` is a non-empty `String`, `Collection`, `Map`, `Matcher`
+- `thing` is a non-zero `Number`
+- `thing` is `true` (if it's a `Boolean`)
+
+This is **different** from Java! `if ("")` is false in Groovy, `if (0)` is false, `if ([])` is false. **Do not** write `if (list != null && !list.isEmpty())` — write `if (list)`.
+
+## Logging
+
+Grails 3 provides a `log` field on every service/controller/domain class:
+
+```groovy
+class OrderService {
+    def place(Order order) {
+        log.info "place_order id=${order.id}"
+        try {
+            // ...
+        } catch (Exception ex) {
+            log.error "place_order_failed id=${order.id}", ex
+            throw ex
+        }
+    }
+}
+```
+
+- Use `log.info "..."` (no parens needed for Groovy method calls)
+- Never use `println` in committed code
+- Include structured key=value pairs; don't write English sentences
+
+## Liquibase Migrations
+
+- **Location:** `grails-app/migrations/` with the master changelog at `grails-app/migrations/changelog.groovy`.
+- **Custom migrations** go under `grails-app/migrations/custom/<yyyy-mm-dd>-<description>.groovy` and are included from the master via an `include file: 'custom/...'` line added in a clearly-scoped commit.
+- **Additive only:** `addColumn`, `createTable`, `addForeignKeyConstraint`. Never edit an existing upstream changeset.
+- **Unique `id` + `author`** on every changeset (the Liquibase DSL requires it).
+- **Preconditions** prevent re-running on already-migrated databases.
+- **Rollback blocks** are encouraged for non-trivial changes.
+
+```groovy
+databaseChangeLog = {
+    changeSet(id: '2026-04-13-01-add-custom-field', author: 'eyeseetea') {
+        preConditions(onFail: 'MARK_RAN') {
+            not { columnExists(tableName: 'product', columnName: 'custom_field') }
+        }
+        addColumn(tableName: 'product') {
+            column(name: 'custom_field', type: 'varchar(255)') {
+                constraints(nullable: true)
+            }
+        }
+    }
+}
+```
+
+## Where New Code Goes (Custom Package Isolation)
+
+- **Domain:** `grails-app/domain/org/pih/warehouse/custom/<feature>/`
+- **Services:** `grails-app/services/org/pih/warehouse/custom/<feature>/`
+- **Controllers:** `grails-app/controllers/org/pih/warehouse/custom/<feature>/`
+- **Views (GSP):** `grails-app/views/custom/<feature>/`
+- **Migrations:** `grails-app/migrations/custom/`
+- **Taglibs:** `grails-app/taglib/org/pih/warehouse/custom/<feature>/`
+
+See `rules/custom-package-isolation.md` for the full rules and rationale.
+
+## What to Avoid
+
+- **JPA annotations** (`@Entity`, `@Column`, `@OneToMany`, `@Id`) — GORM
+- **Spring stereotypes** (`@Service`, `@Repository`, `@Controller`) — Grails conventions handle this
+- **`@Autowired`** — use property-based injection
+- **Java Streams in Groovy** — use closures
+- **`for` loops with mutable accumulators** — use functional collection methods
+- **`println`** in committed code
+- **Raw SQL** without a comment explaining why + parameterization
+- **Modifying existing upstream changesets** — always add a new one under `migrations/custom/`
+- **Boy Scout-style cleanups in upstream files** — suspended here; only apply inside `org.pih.warehouse.custom.*`
diff --git a/.claude/rules/groovy/testing.md b/.claude/rules/groovy/testing.md
new file mode 100644
index 00000000000..015e7e6c3a9
--- /dev/null
+++ b/.claude/rules/groovy/testing.md
@@ -0,0 +1,239 @@
+---
+paths:
+  - "src/test/groovy/**"
+  - "src/integration-test/groovy/**"
+  - "test/**/*.groovy"
+---
+
+# Grails / Groovy Testing — OpenBoxes
+
+## Stack
+
+- **Spock** — primary test framework for Grails services, controllers, and domain classes
+- **Grails test harness** — `grails-app/conf` unit test base classes provide autowiring, in-memory GORM, etc.
+- **JUnit 4/5** — allowed for plain Java helpers in `src/main/java/`, but Groovy code uses Spock
+- **Jacoco** — coverage via `./gradlew jacocoTestReport`
+- **H2 / in-memory** for unit tests; **MySQL** for integration tests
+
+## Test Types
+
+| Type | Location | Base class | Runs with |
+|---|---|---|---|
+| Unit | `src/test/groovy/**` | `Specification` (+ Grails test mixins) | `./gradlew test` |
+| Integration | `src/integration-test/groovy/**` | `Specification` + `@Integration` | `./gradlew integrationTest` |
+| Functional | `src/test/functional/**` | Geb specs | rare; check if still wired |
+
+Match the location of the production code you're testing:
+
+```
+grails-app/services/org/pih/warehouse/custom/foo/FooService.groovy
+src/test/groovy/org/pih/warehouse/custom/foo/FooServiceSpec.groovy
+```
+
+## Spock Spec Anatomy
+
+```groovy
+import grails.testing.services.ServiceUnitTest
+import spock.lang.Specification
+
+class FooServiceSpec extends Specification implements ServiceUnitTest<FooService> {
+
+    def setup() {
+        // runs before each feature method
+    }
+
+    def "createFoo persists a new Foo with the given name"() {
+        given:
+        String name = 'widget-42'
+
+        when:
+        Foo foo = service.createFoo(name)
+
+        then:
+        foo.id != null
+        foo.name == name
+    }
+
+    def "createFoo rejects blank names"() {
+        when:
+        service.createFoo('')
+
+        then:
+        IllegalArgumentException ex = thrown()
+        ex.message.contains('name')
+    }
+}
+```
+
+### Spock blocks
+
+- **`given:`** — test setup (fixtures, inputs)
+- **`when:`** — the action under test
+- **`then:`** — assertions (implicit — each line is an assertion)
+- **`expect:`** — combines when+then for simple cases
+- **`where:`** — data-driven tables
+- **`cleanup:`** — teardown
+
+### Data-driven tests
+
+```groovy
+def "discount is applied correctly"(BigDecimal price, int pct, BigDecimal expected) {
+    expect:
+    pricingService.discount(price, pct) == expected
+
+    where:
+    price        | pct  || expected
+    100.00G      | 10   || 90.00G
+    50.00G       | 0    || 50.00G
+    200.00G      | 25   || 150.00G
+}
+```
+
+Use `G` suffix for `BigDecimal` literals — Groovy's default for decimal literals.
+
+## Mocking
+
+Spock has built-in mocking — do not introduce Mockito for Groovy tests.
+
+```groovy
+def "sends confirmation email on order placed"() {
+    given:
+    EmailService emailService = Mock()
+    service.emailService = emailService
+
+    when:
+    service.placeOrder(new Order(customerEmail: 'a@b.com'))
+
+    then:
+    1 * emailService.send({ it.to == 'a@b.com' })
+}
+```
+
+- **`Mock()`** — strict mock; unexpected invocations are test failures
+- **`Stub()`** — loose stub; records calls but doesn't fail on unexpected ones
+- **`Spy()`** — wraps a real object, allowing partial mocking
+
+### Interaction verification
+
+```groovy
+then:
+1 * emailService.send(_)         // exactly once, any argument
+(1.._) * emailService.send(_)    // at least once
+_ * emailService.send(_)         // any number of times
+0 * _                            // no other interactions on anything
+```
+
+## Unit Test Mixins (Grails-specific)
+
+| Mixin | Purpose |
+|---|---|
+| `ServiceUnitTest<T>` | Service unit tests — autowires the service, provides `service` field |
+| `ControllerUnitTest<T>` | Controller unit tests — autowires the controller, provides `controller` and `params`/`response` |
+| `DomainUnitTest<T>` | Domain class unit tests — provides an in-memory GORM for the single domain |
+| `DataTest` | Multi-domain — `setupData { mockDomains(A, B, C) }` |
+| `TagLibUnitTest<T>` | Taglib unit tests |
+
+```groovy
+class ProductControllerSpec extends Specification implements ControllerUnitTest<ProductController>, DataTest {
+
+    def setupSpec() {
+        mockDomains(Product, Category)
+    }
+
+    def "show renders a product"() {
+        given:
+        Product product = new Product(name: 'Widget', productCode: 'W001').save(failOnError: true)
+
+        when:
+        params.id = product.id
+        controller.show()
+
+        then:
+        response.status == 200
+        response.json.name == 'Widget'
+    }
+}
+```
+
+## Integration Tests
+
+```groovy
+import grails.testing.mixin.integration.Integration
+import spock.lang.Specification
+
+@Integration
+class FooServiceIntegrationSpec extends Specification {
+
+    FooService fooService
+
+    def "integration: createFoo persists to MySQL"() {
+        when:
+        Foo foo = fooService.createFoo('widget-42')
+
+        then:
+        Foo.count() == 1
+        Foo.findByName('widget-42').id == foo.id
+    }
+}
+```
+
+- Integration tests run against a **real Hibernate session** and a **real database** (MySQL or H2 depending on config).
+- They roll back by default after each feature method.
+- Use for anything that needs GORM's full machinery (criteria, HQL, cascades, transactions).
+
+## Assertions
+
+- **Assert concrete values.** Never use `assert result != null` when you can assert the value.
+  ```groovy
+  // BAD
+  result != null
+  result.items.size() > 0
+
+  // GOOD
+  result.items.size() == 3
+  result.items*.name == ['widget', 'gadget', 'gizmo']
+  ```
+- **Spock's power assertion** shows every intermediate value when a line fails — lean on it.
+- **Spread operator (`*.`)** for asserting on collection properties.
+- **`with`** block for grouped assertions on one object:
+  ```groovy
+  then:
+  with(result) {
+      status == 'ACTIVE'
+      items.size() == 3
+      total == 150.00G
+  }
+  ```
+
+## Test Data
+
+- **Domain object creation:** `new Product(name: 'x', productCode: 'p1').save(failOnError: true)` inside `setup()` or `given:`.
+- **Fixture files:** `src/test/resources/` for complex JSON/CSV fixtures.
+- **Builder pattern** for repeated domain setup — extract a helper class under `src/test/groovy/org/pih/warehouse/custom/<feature>/<Feature>TestData.groovy`.
+- **Don't share state between tests** — each feature method should be independent.
+
+## Coverage
+
+- Target: **80%+** on custom feature code (`org.pih.warehouse.custom.**`).
+- Upstream code is exempted — don't chase coverage on files you don't own.
+- Run `./gradlew test jacocoTestReport` and open `build/reports/jacoco/test/html/index.html`.
+
+## What to Avoid
+
+- **Mockito** — use Spock mocks; don't mix frameworks.
+- **JUnit `@Test` annotations in Groovy** — use Spock `def "..."()` feature methods.
+- **Testing upstream code** — they have their own tests. Focus on `org.pih.warehouse.custom.**`.
+- **Tests that sleep** — use `PollingConditions` for async assertions.
+- **Tests that depend on order** — use `@Stepwise` only when genuinely necessary and document why.
+- **Shared mutable fixtures** — each test must be independent.
+- **Asserting on strings that include dates / IDs** — use matchers or extract the volatile part.
+
+## Running Tests
+
+```bash
+./gradlew test                                   # all unit tests
+./gradlew test --tests "*.custom.foo.*"          # filter by pattern
+./gradlew integrationTest                        # integration tests
+./gradlew test jacocoTestReport                  # tests + coverage report
+./gradlew check                                  # tests + static analysis
+```
diff --git a/.claude/rules/java/coding-style.md b/.claude/rules/java/coding-style.md
new file mode 100644
index 00000000000..13066ffc1dc
--- /dev/null
+++ b/.claude/rules/java/coding-style.md
@@ -0,0 +1,127 @@
+---
+paths:
+  - "src/main/java/**/*.java"
+---
+
+# Java Coding Style — OpenBoxes `src/main/java/`
+
+> **Scope:** only the Java helper/utility code under `src/main/java/`. For Groovy/Grails code (the vast majority of the backend), see `rules/groovy/patterns.md` and `rules/groovy/testing.md`.
+
+## Language Floor: Java 8
+
+See `rules/java/patterns.md` for the full list of forbidden features. Short version: **no `var`, no records, no sealed types, no pattern matching, no `List.of()`, no text blocks, no `switch` arrow syntax**.
+
+## Formatting
+
+- Indent with **4 spaces** (match upstream; do not reformat existing files).
+- One public top-level type per file.
+- Member order: constants → instance fields → constructors → public methods → protected → private.
+- Line length: stay under ~120 characters.
+
+## Naming
+
+- `PascalCase` for classes, interfaces, enums
+- `camelCase` for methods, fields, parameters, local variables
+- `SCREAMING_SNAKE_CASE` for `static final` constants
+- Packages lowercase: `org.pih.warehouse.custom.<feature>`
+
+## Immutability
+
+```java
+// GOOD — all fields final, no setters, defensive copies on exposure
+public final class Price {
+    private final BigDecimal amount;
+    private final Currency currency;
+
+    public Price(BigDecimal amount, Currency currency) {
+        this.amount = amount;
+        this.currency = currency;
+    }
+
+    public BigDecimal getAmount() { return amount; }
+    public Currency getCurrency() { return currency; }
+}
+```
+
+## Optional
+
+```java
+// GOOD — Optional return, no get() calls, wrap with orElseThrow
+return orderRepository.findById(id)
+    .map(OrderDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// BAD — Optional as parameter
+public void process(Optional<String> name) { /* ... */ }
+```
+
+## Streams
+
+```java
+// GOOD — short pipeline, named collector
+List<String> activeNames = orders.stream()
+    .filter(Order::isActive)
+    .map(Order::getCustomerName)
+    .collect(Collectors.toList());
+```
+
+- Max 3–4 operations per pipeline; extract helpers otherwise.
+- Use method references (`Order::getCustomerName`) where they improve readability.
+- **No `.toList()` terminal operation** — that's Java 16+.
+
+## Error Handling
+
+- Domain errors: specific `RuntimeException` subclasses.
+- Avoid broad `catch (Exception e)` unless at a top-level handler.
+- Always include context in exception messages.
+- When wrapping, preserve the cause: `new RuntimeException(msg, ex)`.
+
+## Null Handling
+
+- Default to **non-null** for all parameters and return values.
+- Document nullability with `@Nullable` / `@NonNull` when unavoidable (JSR-305 annotations are already on the classpath via Spring/Grails).
+- `Objects.requireNonNull(arg, "arg must not be null")` at the top of public methods where appropriate.
+
+## Logging (SLF4J)
+
+```java
+private static final Logger log = LoggerFactory.getLogger(OrderHelper.class);
+
+log.info("fetch_order id={}", id);
+log.warn("fetch_order_slow id={} durationMs={}", id, duration);
+log.error("fetch_order_failed id={}", id, ex);
+```
+
+- Structured key=value logs, not English sentences.
+- **Never** log secrets, tokens, passwords, or PII.
+- **Never** use `System.out.println` in committed code.
+
+## Project Layout
+
+```
+src/main/java/
+└── org/pih/warehouse/
+    ├── <upstream helpers — do not reformat>
+    └── custom/                         # EyeSeeTea customizations
+        └── <feature>/
+            ├── Helper.java
+            └── Dto.java
+```
+
+**New Java files go under `org.pih.warehouse.custom.<feature>`** per `rules/custom-package-isolation.md`.
+
+## What Not to Do
+
+- No `var`, no records, no sealed classes, no pattern matching, no text blocks.
+- No `@Entity` / `@Column` / JPA annotations — GORM owns persistence.
+- No `@Service` / `@Repository` / `@Component` on new classes — use `grails-app/conf/spring/resources.groovy` for bean registration.
+- No `System.out.println` or `ex.printStackTrace()`.
+- No reformatting of upstream files (Boy Scout Rule is suspended outside the `custom/` subpackage).
+
+## References
+
+- `rules/java/patterns.md` — architectural patterns
+- `rules/java/security.md` — security rules
+- `rules/groovy/patterns.md` — Grails/Groovy backend (the bulk of OpenBoxes)
+- `rules/groovy/testing.md` — Spock + Grails test patterns
+- `rules/custom-package-isolation.md` — where new files go
diff --git a/.claude/rules/java/hooks.md b/.claude/rules/java/hooks.md
new file mode 100644
index 00000000000..8b4557ae05b
--- /dev/null
+++ b/.claude/rules/java/hooks.md
@@ -0,0 +1,22 @@
+---
+paths:
+  - "src/main/java/**/*.java"
+  - "src/test/java/**/*.java"
+---
+
+# Java Hooks — OpenBoxes
+
+> The OpenBoxes backend is mostly Groovy/Grails. The `src/main/java/` tree only holds helpers and utilities. These hooks scope to that subtree only, not to upstream Java files.
+
+## What we run on Java edits
+
+- `./gradlew compileJava` — verify Java helpers still compile against the rest of the build.
+- `./gradlew compileGroovy` — Groovy depends on Java; if Java fails, Groovy fails too.
+
+These are **manual** by default — there are no auto-format / static-analysis hooks committed to the project (`google-java-format`, Checkstyle, SpotBugs are **not** configured in `build.gradle`). Do not introduce them as PreToolUse / PostToolUse hooks here without a team decision; they would touch upstream files and cause merge conflicts.
+
+## What NOT to do
+
+- Do not run Maven (`mvn`, `./mvnw`) — this project is Gradle-only.
+- Do not target `pom.xml` or `*.gradle.kts` — neither exists here.
+- Do not autoformat upstream Java files (Boy Scout Rule is suspended outside `org.pih.warehouse.custom.*`).
diff --git a/.claude/rules/java/patterns.md b/.claude/rules/java/patterns.md
new file mode 100644
index 00000000000..90471488b9c
--- /dev/null
+++ b/.claude/rules/java/patterns.md
@@ -0,0 +1,150 @@
+---
+paths:
+  - "src/main/java/**/*.java"
+---
+
+# Java Patterns — OpenBoxes `src/main/java/`
+
+> **Scope:** only the Java helper/utility code under `src/main/java/`. The main application is **Grails 3 / Groovy** — see `rules/groovy/patterns.md` for everything else.
+
+## Language Floor: Java 8
+
+OpenBoxes runs on **OpenJDK 8**. The following language features do **not** exist and will not compile:
+
+- `var` local-variable inference (Java 10+)
+- `record` types (Java 14+ preview, 16+ stable)
+- `sealed` / `non-sealed` classes (Java 15+ preview, 17+ stable)
+- Pattern matching for `instanceof` (Java 16+)
+- Switch expressions with arrow syntax (Java 14+)
+- Text blocks (`"""..."""`) (Java 15+)
+- `List.of()`, `Map.of()`, `Set.of()` (Java 9+)
+- `String.isBlank()`, `String.strip()`, `String.lines()` (Java 11+)
+- `Optional.isEmpty()` (Java 11+) — use `!opt.isPresent()`
+- `Collectors.toUnmodifiableList()` / `Stream.toList()` (Java 16+) — use `Collectors.toList()` and wrap with `Collections.unmodifiableList`
+
+**Stay on Java 8 syntax for this codebase.** Upstream OpenBoxes pins the JDK via Docker (OpenJDK 8 base) and there is no plan to upgrade.
+
+## Where Java lives
+
+- `src/main/java/` — utility classes, framework extensions, base classes referenced by Groovy
+- `src/main/java/util/` — helpers
+- `src/main/java/org/pih/warehouse/` — supporting Java code (e.g. interceptors, annotation classes)
+
+**New custom Java code goes under `src/main/java/org/pih/warehouse/custom/<feature>/`** per the Upstream Compatibility rules. See `rules/custom-package-isolation.md`.
+
+## Framework Context
+
+The Java helpers run inside a **Grails 3 application on Spring Boot**. Beans are wired by Grails' convention-based injection, not by Spring stereotypes. This means:
+
+- **No `@Service`, `@Repository`, `@Component`, `@Controller`** on new Java classes — Grails does not scan them. If a Java class needs to be a Spring bean, register it in `grails-app/conf/spring/resources.groovy`.
+- **No `@Autowired`** — Grails expects property-based injection from Groovy callers. If a Java bean has dependencies, declare a setter and let Spring set it, or pass them via constructor and wire it in `resources.groovy`.
+- **No JPA.** GORM owns persistence. A Java helper should never define a `@Entity` — if you need a domain class, write it as a Groovy GORM class in `grails-app/domain/`.
+
+## Immutability
+
+- Mark fields `final` by default.
+- Return defensive copies from public getters: `Collections.unmodifiableList(items)`.
+- Do not expose mutable internals.
+
+```java
+public final class OrderSummary {
+    private final Long id;
+    private final String customerName;
+    private final BigDecimal total;
+
+    public OrderSummary(Long id, String customerName, BigDecimal total) {
+        this.id = id;
+        this.customerName = customerName;
+        this.total = total;
+    }
+
+    public Long getId() { return id; }
+    public String getCustomerName() { return customerName; }
+    public BigDecimal getTotal() { return total; }
+}
+```
+
+No records. Write a plain immutable class with final fields and a public constructor.
+
+## Optional Usage
+
+- `Optional<T>` for return types of methods that may return "no result".
+- Use `map()`, `flatMap()`, `orElseThrow()`, `ifPresent()` — never call `get()` without a preceding `isPresent()` check (or better, don't call `get()` at all).
+- Do **not** use `Optional` as a field type, method parameter, or collection element.
+
+```java
+public Optional<Order> findById(Long id) {
+    return Optional.ofNullable(orders.get(id));
+}
+
+// Usage
+Order order = findById(id).orElseThrow(
+    () -> new IllegalStateException("Order not found: " + id));
+```
+
+## Streams (keep short and simple)
+
+```java
+List<String> names = orders.stream()
+    .map(Order::getCustomerName)
+    .filter(Objects::nonNull)
+    .collect(Collectors.toList());
+```
+
+- 3–4 operations max; if it's longer, extract a helper method.
+- Avoid side effects in stream operations — no mutation of shared state inside `.forEach()`.
+- **No `toList()` terminal op** — that's Java 16+. Use `collect(Collectors.toList())`.
+- For small collections, a plain `for` loop is fine and often clearer.
+
+## Error Handling
+
+- Prefer unchecked exceptions (`RuntimeException` subclasses) for domain errors.
+- Create specific exception types with context: `new OrderNotFoundException(id)`.
+- Avoid catching `Exception` unless rethrowing or logging at a top-level boundary.
+- Include the original cause when wrapping: `new RuntimeException(msg, cause)`.
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+## Logging
+
+Use SLF4J — it's already on the classpath via Grails:
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class OrderHelper {
+    private static final Logger log = LoggerFactory.getLogger(OrderHelper.class);
+
+    public void process(Long id) {
+        log.info("process_order id={}", id);
+        try {
+            // ...
+        } catch (RuntimeException ex) {
+            log.error("process_order_failed id={}", id, ex);
+            throw ex;
+        }
+    }
+}
+```
+
+Do **not** use `System.out.println`.
+
+## What to Avoid
+
+- **JPA annotations** (`@Entity`, `@Table`, `@Column`, `@Id`) — use GORM in Groovy domain classes.
+- **Spring stereotypes** (`@Service`, `@Repository`, `@Component`) on new Java classes — register beans in `resources.groovy` instead.
+- **`@Autowired` / constructor injection** without a matching `resources.groovy` entry — Grails won't wire it automatically for arbitrary Java classes.
+- **Java 9+ features** — none of them compile.
+- **Raw types** (`List` instead of `List<String>`) — always parameterize.
+
+## References
+
+- For Groovy / Grails code, see `rules/groovy/patterns.md`.
+- For custom-code isolation, see `rules/custom-package-isolation.md`.
diff --git a/.claude/rules/java/security.md b/.claude/rules/java/security.md
new file mode 100644
index 00000000000..a1545b70962
--- /dev/null
+++ b/.claude/rules/java/security.md
@@ -0,0 +1,94 @@
+---
+paths:
+  - "src/main/java/**/*.java"
+---
+
+# Java Security — OpenBoxes `src/main/java/`
+
+> **Scope:** Java helper code only. Main Grails application security is governed by the Grails spring-security-core plugin and the rules in `rules/groovy/security.md`.
+
+## Secrets
+
+- **Never hardcode** credentials, API keys, or tokens in source.
+- Read from environment variables or the externalized Grails config:
+  ```java
+  String apiKey = System.getenv("INTEGRATION_API_KEY");
+  Objects.requireNonNull(apiKey, "INTEGRATION_API_KEY must be set");
+  ```
+- Do not put secrets in `grails-app/conf/application.yml` or `application.groovy` — use an external config file path (`grails.config.locations`) or env vars.
+
+## SQL Injection
+
+- **Never concatenate user input into SQL.** Use `PreparedStatement` with positional parameters.
+- Prefer going through Grails/GORM (in Groovy) rather than raw JDBC in Java helpers. If you're writing raw JDBC in a Java helper, you probably should have written it as a Groovy service using criteria queries.
+
+```java
+// BAD
+stmt.executeQuery("SELECT * FROM products WHERE name = '" + name + "'");
+
+// GOOD
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM products WHERE name = ?");
+ps.setString(1, name);
+ResultSet rs = ps.executeQuery();
+```
+
+## Input Validation
+
+- Validate at the boundary. Use plain guard clauses:
+  ```java
+  if (customerName == null || customerName.trim().isEmpty()) {
+      throw new IllegalArgumentException("customerName is required");
+  }
+  ```
+- **Note:** `String.isBlank()` does not exist on Java 8 — use `.trim().isEmpty()`.
+- For file paths, always normalize with `Paths.get(...).normalize()` and verify the result stays under an allowed root directory (path traversal defense).
+
+## File I/O
+
+- Never construct a `File` or `Path` from user input without validating it stays inside an allowed directory.
+- Close resources with try-with-resources:
+  ```java
+  try (InputStream in = Files.newInputStream(path)) {
+      // ...
+  }
+  ```
+
+## Authentication / Authorization
+
+- Auth is handled by the Grails spring-security-core plugin in the main app. Java helpers should never implement their own authentication.
+- If a Java helper needs to check the current user, get it from the Grails security service via `resources.groovy` injection — do not reach into the `SecurityContextHolder` directly unless you know the Grails plugin has populated it.
+
+## Error Messages
+
+- **Never expose stack traces, internal paths, or raw exception messages to users.** Log server-side; return generic messages at the API boundary.
+- Avoid `ex.getMessage()` in API responses — it often contains SQL fragments or file paths.
+
+```java
+try {
+    return orderService.findById(id);
+} catch (OrderNotFoundException ex) {
+    log.warn("Order not found: id={}", id);
+    throw new NotFoundApiException("Resource not found");  // generic, no internals
+} catch (RuntimeException ex) {
+    log.error("Unexpected error processing order id={}", id, ex);
+    throw new InternalApiException("Internal server error");
+}
+```
+
+## Dependency Hygiene
+
+- New dependencies in `build.gradle` need justification — every transitive dep is a supply-chain surface.
+- Run `./gradlew dependencyCheckAnalyze` before a release (OWASP Dependency Check is already configured).
+- Keep Spring Boot / Grails on supported versions (bound by upstream).
+
+## What to Avoid
+
+- `eval`-like reflection on user-controlled class names
+- XML parsing without XXE protection — use `XMLInputFactory` with `IS_SUPPORTING_EXTERNAL_ENTITIES = false`
+- Insecure deserialization (`ObjectInputStream` on untrusted streams)
+- Hardcoded passwords in test fixtures that might get copy-pasted into production
+
+## References
+
+- `rules/groovy/security.md` — main application security rules
+- `rules/java/patterns.md` — Java 8 patterns and forbidden features
diff --git a/.claude/rules/web/coding-style.md b/.claude/rules/web/coding-style.md
new file mode 100644
index 00000000000..26568775dac
--- /dev/null
+++ b/.claude/rules/web/coding-style.md
@@ -0,0 +1,108 @@
+---
+paths:
+  - "src/js/**"
+---
+
+# Frontend Coding Style — OpenBoxes
+
+## Language Floor
+
+- **Node 14**, **React 16.8**, **ES2020 via Babel**. Avoid features that require newer runtimes:
+  - **No optional chaining (`?.`) or nullish coalescing (`??`) in Webpack config or build scripts** — they run on raw Node 14. Use them freely in application code (Babel transpiles them).
+  - **No top-level `await`.** Wrap in an async IIFE if needed.
+  - **No private class fields (`#foo`)** — Babel preset in this project doesn't guarantee them.
+- **No TypeScript.** OpenBoxes is JS + JSX. Don't introduce `.ts`/`.tsx` files. Use JSDoc `@param` / `@returns` for non-trivial utilities if documentation helps.
+
+## File Extensions
+
+- Files containing JSX → `.jsx`
+- Files with only plain JS → `.js`
+- Match the existing convention in the neighbor directory.
+
+## Modules
+
+- `import` / `export` only. No `require()` in `src/js/`.
+- Absolute imports resolve from `src/js/` via the `moduleDirectories` Jest config.
+- Use **named imports** for large libraries to preserve tree-shaking:
+  ```js
+  // GOOD
+  import { isEmpty, debounce } from 'lodash';
+  // BAD
+  import _ from 'lodash';
+  ```
+- **Do not import from `lodash/fp`** — not in dependencies.
+- Import order (enforced by `eslint-plugin-simple-import-sort`): builtin → external → absolute → relative.
+
+## Variables
+
+- `const` by default, `let` when reassignment is required.
+- **No `var`.** Existing uses are legacy; don't add more.
+- Prefer destructuring for props and state.
+
+## Naming
+
+- **Components:** `PascalCase` (`StockMovementList`, `AddItemsPage`)
+- **Hooks:** `useCamelCase` (`useInboundFilters`)
+- **Redux action types:** `SCREAMING_SNAKE_CASE` constants
+- **Action creators / reducers:** `camelCase`
+- **File names:** match the default export — `StockMovementList.jsx`, `useInboundFilters.jsx`
+- **CSS classes:** kebab-case, scoped via SCSS module or component folder
+
+## React Components
+
+- **Functional components + hooks** for new code. Existing class components can stay until touched; don't mass-convert.
+- **Default-export the component**; use named exports for helpers in the same file sparingly.
+- **Props destructuring** at the top of the function body:
+  ```jsx
+  const AddItemsPage = ({ items, onSubmit, translate }) => {
+    // ...
+  };
+  ```
+- **PropTypes** for public components (the project uses `prop-types`). For new internal components, PropTypes are still preferred but not mandatory — match the surrounding file.
+
+## Hooks Rules
+
+- **Rules of hooks:** only call hooks at the top level, never inside loops or conditions.
+- **Exhaustive dependency arrays.** If `eslint-plugin-react-hooks` flags a missing dep, fix the dep — don't suppress the rule.
+- **Custom hooks** live in `src/js/hooks/` mirroring the feature structure (`hooks/list-pages/<feature>/`).
+- **No side effects in render.** Move to `useEffect` or event handlers.
+
+## Redux
+
+- **Existing pattern:** actions in `src/js/actions/`, reducers in `src/js/reducers/`, selectors in `src/js/selectors/`. Follow it.
+- **Immutable updates.** Use `immutability-helper` (already in deps) for deeply nested updates, or return a new object via spread.
+- **Do not mutate state.** `state.items.push(...)` is a bug.
+- **Selectors should be memoized** via `reselect` (`createSelector`) when they compute derived values.
+- **`redux-persist` whitelist** — see `rules/web/security.md`. Default new state to **not** persisted.
+
+## Forms
+
+- **New forms:** prefer `react-hook-form` + `zod` schemas. Put the schema in a sibling `schemes/` or `validation.js` file, not inline (the existing convention in this codebase is `schemes/`, e.g. `src/js/utils/form-values/schemes/cycleCountSchemes.js` — do not create a parallel `schemas/` folder).
+- **Existing wizards:** `react-final-form` + `react-final-form-arrays`. Don't mix libraries inside a single wizard.
+- **Never inline form validators** that are reused across steps — extract to `src/js/utils/validation.js` or a feature-specific file.
+
+## Styling
+
+- **SCSS** in a sibling file (`Component.scss`) imported at the top of the component.
+- **Bootstrap 4.6** utility classes first (`d-flex`, `align-items-center`, `col-md-6`). Custom CSS only when utilities don't cover the case.
+- **No inline styles** except for dynamic values that can't be expressed as a class (computed colors, pixel offsets from refs). Even then, use `className` conditionals where possible.
+- **No CSS-in-JS libraries.** The stack doesn't use emotion/styled-components and adding them is overkill.
+
+## Comments
+
+- Default to **no comments** — well-named identifiers document intent.
+- Comment only the **why** of non-obvious code: workarounds, browser quirks, subtle data-shape assumptions.
+- Never reference issue numbers, the current task, or callers (`// added for OBPIH-7718`). That information belongs in git history.
+
+## Functional Style
+
+- **`.map` / `.filter` / `.reduce` / `.flatMap`** over `for` loops. The codebase already leans this way ~75:1; match it.
+- **`Array.from(Object.entries(...))` + `.reduce`** over `for...in`.
+- **Avoid mutating function arguments.** Return a new value.
+
+## Anti-Patterns
+
+- **No `moment` for new date code** — the project has `date-fns` v4. `moment` is still a dep for legacy reasons; don't add new `moment` calls.
+- **No `jquery` in React code.** It's present for legacy GSP pages only.
+- **No `eval`, no `new Function(...)`, no `with {}`.**
+- **No `console.log` in committed code.** Use the logger pattern (Sentry + `apiClient` error interceptor).
diff --git a/.claude/rules/web/design-quality.md b/.claude/rules/web/design-quality.md
new file mode 100644
index 00000000000..22fe1fc4749
--- /dev/null
+++ b/.claude/rules/web/design-quality.md
@@ -0,0 +1,67 @@
+---
+paths:
+  - "src/js/**"
+  - "grails-app/views/**"
+---
+
+# UI Quality — OpenBoxes Frontend
+
+OpenBoxes is a **data-heavy logistics admin app**, not a marketing site. The visual priorities are **density, scannability, and predictability** — not hero sections, scrollytelling, or editorial layouts. Rules here target the admin-app reality.
+
+## Stack Constraints
+
+- **Bootstrap 4.6** + SCSS is the foundation. Use Bootstrap utilities and components first; custom CSS is a fallback.
+- **Font Awesome 5** icons via `@fortawesome/react-fontawesome`. Don't mix icon libraries.
+- **react-tippy** for tooltips, **react-modal** for modals, **react-confirm-alert** for confirmations — stick with what's in use.
+- **`react-table` / `react-virtualized` / `@tanstack/react-table`** are all present — use the one already used by the surrounding screen rather than introducing a new one.
+
+## Hierarchy and Density
+
+- Forms should group fields by logical section with clear headings. Wizard steps (`src/js/components/stock-movement-wizard/**`) are the template to follow.
+- Tables should expose the most-scanned column first (usually product code/SKU), with secondary data right-aligned (qty, value).
+- **Don't pad aggressively.** This is an admin app; compact layouts let users scan 50+ rows without scrolling.
+
+## Consistency Before Creativity
+
+- New screens should match the visual language of existing screens in the same area. Inbound-list, outbound-list, stock-list all follow a list-page pattern (`src/js/hooks/list-pages/**`) — copy it.
+- When adding a new wizard step, match the existing wizard step layout (header, breadcrumbs, save/cancel row).
+- Modals should use the existing `ModalWrapper` (`src/js/components/form-elements/ModalWrapper.jsx`) pattern.
+
+## States to Always Design
+
+Every interactive element needs explicit visual states:
+
+- **Default, hover, focus, active, disabled, loading**
+- **Empty state** (list with no data) — use an informative empty state, not a blank area
+- **Error state** (API failure) — use the existing `AlertMessage` pattern
+- **Loading state** — use `react-spinners` or skeleton placeholders; never leave a component with stale data
+
+## Accessibility Minimums
+
+- Use semantic HTML: `<button>` for actions, `<a>` for navigation, `<table>` / `<th>` / `<td>` for tabular data.
+- Every icon-only button needs an `aria-label` or `title`.
+- Focus order must be logical; test keyboard navigation on any new form or wizard step.
+- Form labels must be associated with inputs (`<label htmlFor>` or wrapping).
+
+## Internationalization
+
+- **All user-facing strings must go through `react-localize-redux`.** No literal English strings in JSX. New keys go in the translations JSON and the default strings.
+- Format dates with `date-fns` (v4), numbers with `Intl.NumberFormat`. Don't hardcode formats.
+- Currency, units, and formats are locale-dependent — respect the user's locale.
+
+## Anti-Patterns for This App
+
+- **Don't reach for glassmorphism, neo-brutalism, or bento layouts.** They don't fit a data-entry tool and will look out of place next to existing screens.
+- **Don't introduce motion that delays interaction.** Animations longer than ~200ms feel slow in a tool users spend 8 hours in.
+- **Don't auto-scroll or animate on data refresh.** Users lose their place.
+- **Don't dark-mode-by-default.** The app has one theme; don't invent a second one without coordination.
+
+## Checklist
+
+- [ ] Matches the visual language of adjacent screens
+- [ ] Uses the same table/form/modal components as its neighbors
+- [ ] Defines all interactive states (including empty, error, loading)
+- [ ] Passes keyboard navigation test
+- [ ] All strings go through `react-localize-redux`
+- [ ] Semantic HTML (`<button>`, `<table>`, `<label for>`)
+- [ ] No new design tokens or color variables without justification
diff --git a/.claude/rules/web/patterns.md b/.claude/rules/web/patterns.md
new file mode 100644
index 00000000000..5ec893021ef
--- /dev/null
+++ b/.claude/rules/web/patterns.md
@@ -0,0 +1,166 @@
+---
+paths:
+  - "src/js/**"
+---
+
+# Frontend Patterns — OpenBoxes
+
+## Component Architecture
+
+### Where components live
+
+```
+src/js/
+├── components/
+│   ├── <feature>/             # screens / pages for a feature
+│   ├── form-elements/         # shared form inputs, table, modals
+│   ├── Layout/                # header, footer, navbar, menu
+│   ├── DataTable/             # shared table widgets
+│   └── ...
+├── custom/                    # EyeSeeTea customizations (NEW code goes here)
+├── hooks/                     # custom hooks, mirrors feature folders
+├── actions/                   # Redux action creators
+├── reducers/                  # Redux reducers
+├── selectors/                 # memoized selectors (reselect)
+├── utils/                     # shared helpers (apiClient, form utils, etc.)
+├── consts/                    # constants, enums
+└── schemes/                   # zod validation schemas
+```
+
+**New custom code goes under `src/js/custom/<feature>/`** per the Upstream Compatibility rules. See `rules/custom-package-isolation.md`.
+
+### Container vs presentational
+
+- **Container components** own data loading (thunks, API calls, `useEffect`) and subscribe to Redux.
+- **Presentational components** receive props, render UI, emit callbacks. No direct Redux access.
+- Existing code mixes both patterns — when touching a mixed component, don't force a refactor. When creating new, prefer this split.
+
+### Hook-first for new code
+
+Class components still exist (`src/js/components/stock-movement-wizard/**/*.jsx`) — leave them alone unless you're actively working on one. **New components should be function components + hooks.**
+
+## State Management
+
+| State type | Where it lives | Tool |
+|---|---|---|
+| **Server data** (entities, lists) | Redux, populated via thunks | `redux-thunk`, `redux-promise` |
+| **Form state** | react-final-form (legacy wizards) or react-hook-form (new) | see Forms below |
+| **URL state** (filters, pagination, search) | Query params via `query-string` | `useHistory` from `react-router-dom` |
+| **Ephemeral UI state** (modal open, hover) | `useState` inside the component | React |
+| **Cross-component ephemeral** (current location, auth) | Redux | `react-redux` |
+
+### Do not duplicate
+
+- Never mirror server state into local `useState` — re-derive with selectors.
+- Never mirror URL state into Redux — read it from `useLocation` / query-string.
+
+### Selectors
+
+Use `reselect` for derived values. Selector naming: `getXxx` for plain access, `selectXxxByY` for parameterized:
+
+```js
+import { createSelector } from 'reselect';
+
+export const getProducts = (state) => state.products.byId;
+export const getActiveProducts = createSelector(
+  getProducts,
+  (products) => Object.values(products).filter((p) => p.active),
+);
+```
+
+## API Calls
+
+- **Always** use the shared `apiClient` from `src/js/utils/apiClient.jsx`.
+- **Thunk pattern** for async actions:
+  ```js
+  export const fetchProducts = () => async (dispatch) => {
+    dispatch({ type: FETCH_PRODUCTS_REQUEST });
+    try {
+      const { data } = await apiClient.get('/openboxes/api/products');
+      dispatch({ type: FETCH_PRODUCTS_SUCCESS, payload: data });
+    } catch (err) {
+      dispatch({ type: FETCH_PRODUCTS_FAILURE, payload: err });
+    }
+  };
+  ```
+- **Endpoints:** backend routes are under `/openboxes/api/...`. Do not hardcode hostnames — `apiClient` handles the base URL.
+- **Query cancellation:** use `cwait` (already a dep) for concurrency limits on bulk operations.
+
+## Forms
+
+### Wizard pages (`react-final-form`)
+
+The stock-movement wizards are the reference. Each step is a connected component that reads current form values and emits the next step:
+
+```jsx
+<Form onSubmit={onSubmit} initialValues={values}>
+  {({ handleSubmit, values }) => (
+    <form onSubmit={handleSubmit}>
+      <Field name="product.id" component={ProductSelect} />
+      <FieldArray name="lineItems">
+        {({ fields }) => fields.map((name, i) => <LineItemRow key={i} name={name} />)}
+      </FieldArray>
+    </form>
+  )}
+</Form>
+```
+
+- **FieldArray** for repeatable rows.
+- **Validators** go in `src/js/utils/validators.jsx` or a feature-specific file — never inline in JSX.
+
+### New forms (`react-hook-form` + `zod`)
+
+```jsx
+const schema = z.object({
+  name: z.string().min(1),
+  quantity: z.number().int().positive(),
+});
+
+const { register, handleSubmit, formState: { errors } } = useForm({
+  resolver: zodResolver(schema),
+});
+```
+
+- **Schemas live in `src/js/schemes/<feature>.js`** — the project already follows this convention (`src/js/schemes/cycleCountSchemes.js`).
+
+### Never mix libraries
+
+One wizard, one form library. Don't introduce `react-hook-form` into an existing `react-final-form` wizard mid-flight.
+
+## Tables
+
+- **`react-table` v6** — older API, in use for most lists (`src/js/components/<feature>/...ListTable.jsx`)
+- **`@tanstack/react-table` v8** — new API, used in newer tables (`src/js/components/DataTable/v2/*`)
+- **`react-virtualized`** — used where thousands of rows are expected
+
+Match the neighbor file. Don't introduce a fourth table library.
+
+## Routing
+
+- `react-router-dom` v5 (not v6). Use `<Route>`, `<Switch>`, `<Redirect>`, and the `useHistory` / `useLocation` / `useParams` hooks.
+- **Lazy-loaded routes** via `react-loadable`. Keep the bundle-splitting boundary at the route level.
+
+## Internationalization
+
+- All user-facing text goes through `react-localize-redux`:
+  ```jsx
+  import { Translate } from 'react-localize-redux';
+  <Translate id="stockMovement.createTitle" defaultMessage="Create Stock Movement" />
+  ```
+- New keys go in the translation JSON files under `src/js/locale/` (or wherever the project stores them — match the existing convention).
+
+## Error Handling
+
+- **Use the existing `AlertMessage` component** for user-facing errors.
+- **`react-confirm-alert`** for destructive confirmations.
+- **Sentry** (`@sentry/react`) catches uncaught errors; wrap risky async boundaries with an `ErrorBoundary`.
+- **Never swallow errors silently.** An empty `.catch(() => {})` is a bug.
+
+## Anti-Patterns
+
+- **Mutating Redux state.** Always return new objects.
+- **`useEffect` for derived state.** Compute at render time or use `useMemo`.
+- **Props drilling past 2 levels.** Use context or connect the deeper component directly.
+- **`key={index}`** in dynamic lists. Use a stable ID.
+- **`useEffect(() => { ... }, [])` for data fetching without cleanup** — leaks on unmount.
+- **`setState` inside render** — infinite loop.
diff --git a/.claude/rules/web/performance.md b/.claude/rules/web/performance.md
new file mode 100644
index 00000000000..d04cac369e6
--- /dev/null
+++ b/.claude/rules/web/performance.md
@@ -0,0 +1,81 @@
+---
+paths:
+  - "src/js/**"
+  - "webpack.config.js"
+---
+
+# Frontend Performance — OpenBoxes
+
+OpenBoxes is an **admin SPA** used 8 hours a day with large datasets (10k+ rows, nested wizards). Performance priorities are **render responsiveness, render count, and bundle size** — not landing-page Core Web Vitals.
+
+## Bundle
+
+- **Webpack 5 production build** (`npm run bundle`) is the authoritative bundle. Inspect output size when adding dependencies.
+- **Route-level code splitting** via `react-loadable` is the existing pattern. New feature screens should be lazy-loaded at the route boundary.
+- **Avoid full-library imports:**
+  ```js
+  // BAD — imports all of lodash (~70kb)
+  import _ from 'lodash';
+  // GOOD — tree-shakeable
+  import { isEmpty, debounce } from 'lodash';
+  ```
+- **Large libraries to watch:** `moment` (legacy — prefer `date-fns`), `chart.js`, `react-virtualized`, `@tanstack/react-virtual`.
+
+## Tables and Long Lists
+
+This is the single biggest performance topic for OpenBoxes.
+
+- **Virtualize anything > 100 rows.** Use `react-virtualized`, `@tanstack/react-virtual`, or the existing virtualized components (`src/js/components/cycleCount/toCountTab/VirtualizedTablesList.jsx`).
+- **`react-table-hoc-fixed-columns`** is in use for wide tables with sticky columns — don't reinvent.
+- **Server-side pagination** for lists that could exceed a few hundred rows. Never load 10k rows and then paginate client-side.
+- **Debounce search/filter inputs** (`lodash.debounce`, 250–400ms) so every keystroke doesn't refire queries.
+
+## Render Count
+
+- **`React.memo`** on presentational list row components — a 10k-row table re-rendering every row on hover is the #1 perf bug.
+- **`useCallback` / `useMemo`** for props passed to memoized children. Inline arrow functions in props defeat memoization.
+- **Stable keys.** `key={index}` on a filterable list causes React to reconcile everything. Use a stable ID.
+- **Reselect** for derived Redux state — avoids recalculating derived values on every state change.
+
+## API Call Efficiency
+
+- **Batch reference data** (categories, locations, UoMs) at app boot or via a shared Redux slice — don't refetch per component.
+- **No N+1 fetches.** If you find yourself calling `GET /api/product/:id` inside a `.map(...)`, batch via a `GET /api/product?ids=...` endpoint or via a `Promise.all` if the backend supports it.
+- **`cwait`** for concurrency limits on bulk operations (already a dependency).
+- **Cancel in-flight requests on unmount.** Use axios `CancelToken` or the newer `AbortController` pattern; the shared `apiClient` supports it.
+
+## Forms
+
+- **`react-final-form`** re-renders aggressively. Use `<FormSpy subscription={{ values: true }}>` to limit what triggers a re-render.
+- **Field arrays** (`react-final-form-arrays`) with 100+ rows are expensive — consider chunking or virtualizing.
+- **Zod validation** on every keystroke can be slow — debounce or validate on blur for large forms.
+
+## Charts
+
+- **`chart.js` v2.9** is in use via `react-chartjs-2`. Don't upgrade chart.js without testing; v3+ is a breaking change.
+- **Destroy chart instances on unmount** to avoid canvas memory leaks.
+
+## Webpack / Build
+
+- **Node 14** for the build toolchain. Don't upgrade Webpack without confirming Node 14 compatibility.
+- **No optional chaining (`?.`) in `webpack.config.js`** — it runs on raw Node 14 outside of Babel.
+- **Watch mode:** `npm run watch` uses HMR where possible; re-running full webpack is slow (~30–60s).
+
+## Anti-Patterns
+
+- **Loading full product/location catalogs into Redux at app boot.** Lazy-load by page.
+- **Unbounded `useEffect` dependencies** causing infinite re-renders.
+- **Synchronous JSON parsing** of 5MB+ API responses — chunk on the server instead.
+- **`setState` inside `useEffect` without a guard** — causes re-renders in a loop.
+- **Inline object/array literals as Redux selector results** — breaks shallow equality and re-renders everything subscribed.
+
+## Perf Review Checklist
+
+- [ ] New list views virtualize beyond 100 rows
+- [ ] New deps are tree-shaken or imported by name
+- [ ] No N+1 API calls inside `.map()` / loops
+- [ ] `React.memo` + `useCallback` on row components in large tables
+- [ ] Debounced search/filter inputs
+- [ ] `apiClient` requests cancelled on unmount
+- [ ] Reselect used for derived Redux state
+- [ ] Bundle size inspected after adding a dep (`npm run bundle && ls -la src/main/webapp/webpack`)
diff --git a/.claude/rules/web/security.md b/.claude/rules/web/security.md
new file mode 100644
index 00000000000..80bca1ad35a
--- /dev/null
+++ b/.claude/rules/web/security.md
@@ -0,0 +1,63 @@
+---
+paths:
+  - "src/js/**"
+  - "grails-app/views/**"
+  - "grails-app/assets/**"
+---
+
+# Web Security — OpenBoxes Frontend
+
+## XSS Prevention
+
+- **Never use `dangerouslySetInnerHTML`** unless content is sanitized with a vetted library (DOMPurify) first. Even then, prefer rendering JSX.
+- **`react-html-parser`** is in use in this repo — treat its input as untrusted. Always sanitize user-supplied HTML before parsing.
+- **GSP views** (`grails-app/views/**/*.gsp`): use `${...}` which escapes by default. Never use `<%= %>` or `raw()` / `.encodeAsRaw()` with user input.
+- **Axios responses**: don't inject raw response HTML into the DOM. If the backend returns HTML, render it as text or sanitize.
+
+## Input Validation
+
+- Validate on **both** client and server. Client-side validation is for UX; never trust it for security.
+- Use `zod` schemas for new forms (already a dependency). Existing forms use `react-final-form` validators — keep the pattern consistent within a given wizard.
+- Reject input at the boundary with a clear error; never silently coerce.
+
+## API Calls
+
+- **Always use the shared `apiClient`** (`src/js/utils/apiClient.jsx`) — never `fetch` or a bare `axios` instance. The shared client handles auth, CSRF, and error interceptors.
+- **CSRF:** the backend issues a CSRF token; the shared `apiClient` attaches it. If you're tempted to bypass the shared client, don't — you'll lose CSRF protection.
+- **Never put secrets in `src/js/`** — anything shipped to the browser is public. Use `process.env.*` only for build-time, non-sensitive config.
+
+## Sensitive Data
+
+- **No PII in console logs.** `console.log` left in production code is both a security and quality issue. Use the existing Sentry integration (`@sentry/react`) for error reporting.
+- **No secrets in Redux state** — Redux is persisted via `redux-persist` into localStorage. Tokens, passwords, API keys must never go through Redux.
+- **`redux-persist` whitelists**: when adding a new reducer, review whether its state should be persisted. Default to **not** persisting user-specific or sensitive state.
+
+## File Uploads
+
+- Validate MIME type and size on the client for UX, and **always** validate again server-side.
+- `react-dropzone` is the standard — use its `accept` and `maxSize` props.
+- Never display a server path or internal filename to users in error messages.
+
+## Third-Party Scripts
+
+- New runtime dependencies must be justified in the PR description. Prefer existing utilities over adding new packages — every dep is a supply-chain surface.
+- Respect the Node 14 / React 16.8 version floors when evaluating packages; many modern packages won't install or will ship unsupported syntax.
+
+## URLs and Redirects
+
+- Never redirect to a URL pulled from `query-string` params without validating it against an allowlist. Open redirects are a common phishing vector in admin apps.
+- `react-router-dom` v5 is in use — use `<Redirect>` and `history.push()`, not `window.location = ...`.
+
+## Logging and Error Reporting
+
+- Use Sentry for client errors; redact user PII (names, emails, addresses) from breadcrumbs via Sentry's `beforeSend`.
+- Never log request bodies or response bodies that might contain inventory-sensitive data (lot numbers, quantities, supplier prices).
+
+## Checklist
+
+- [ ] No `dangerouslySetInnerHTML` with unsanitized input
+- [ ] API calls go through `apiClient`, not bare axios/fetch
+- [ ] No secrets in source, Redux, or localStorage
+- [ ] Forms validate on both client and server
+- [ ] Redirects validated against allowlist
+- [ ] No `console.log` with user data
diff --git a/.claude/rules/web/testing.md b/.claude/rules/web/testing.md
new file mode 100644
index 00000000000..1488c29cd89
--- /dev/null
+++ b/.claude/rules/web/testing.md
@@ -0,0 +1,120 @@
+---
+paths:
+  - "src/js/**"
+---
+
+# Frontend Testing — OpenBoxes
+
+## Stack
+
+- **Jest 29** — runner, `testEnvironment: jsdom`, config in `package.json`
+- **@testing-library/react 12** — component queries and user interaction
+- **@testing-library/react-hooks 8** — hook testing in isolation (React 16.8 compatible)
+- **@testing-library/jest-dom** — DOM matchers (`toBeInTheDocument`, `toHaveAttribute`, …)
+- **mock-local-storage** — auto-mocked via `setupFilesAfterEach`
+- **redux-mock-store** — mock Redux stores in connected component tests
+
+No Playwright, no Cypress, no Vitest — don't introduce new test runners.
+
+## Where tests live
+
+- Component tests: sibling `__tests__/` folder or `<name>.test.jsx` sibling file — match the neighbor's convention.
+- Utility tests: `src/js/tests/utils/<name>.test.jsx`
+- Hook tests: `src/js/tests/hooks/<name>.test.jsx` or inside the feature folder
+
+Jest roots: `src/` (see `package.json` → `jest.roots`).
+
+## Assertions
+
+- **Assert concrete values.** Never `expect(value).toBeTruthy()` or `expect(result).toBeDefined()` when you can assert the exact value.
+  ```js
+  // BAD
+  expect(result).toBeDefined();
+  expect(screen.getByRole('button')).toBeTruthy();
+
+  // GOOD
+  expect(result).toEqual({ id: 1, name: 'Widget' });
+  expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument();
+  ```
+- **Use `describe` blocks** to group related tests by feature or scenario.
+- **Extract constants** for repeated strings (class names, error messages, API paths).
+- **Remove redundant tests** — if a stronger assertion exists, delete the weaker one.
+
+## Component tests (RTL)
+
+```jsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+
+describe('QuantityInput', () => {
+  it('calls onChange with the parsed integer', async () => {
+    const onChange = jest.fn();
+    render(<QuantityInput onChange={onChange} />);
+
+    await userEvent.type(screen.getByRole('spinbutton'), '42');
+
+    expect(onChange).toHaveBeenCalledWith(42);
+  });
+});
+```
+
+- **Query by role first**, then label, then text. Only fall back to `getByTestId` when nothing else works — test IDs are a last resort.
+- **Use `userEvent` over `fireEvent`** for realistic interactions.
+- **Never test implementation details** (state shape, internal method calls). Test what the user sees.
+
+## Connected component tests (Redux)
+
+```jsx
+import { Provider } from 'react-redux';
+import configureStore from 'redux-mock-store';
+import thunk from 'redux-thunk';
+
+const mockStore = configureStore([thunk]);
+
+const renderWithStore = (state, ui) => {
+  const store = mockStore(state);
+  return { store, ...render(<Provider store={store}>{ui}</Provider>) };
+};
+```
+
+- **Assert on dispatched actions** for thunks: `expect(store.getActions()).toEqual([...])`.
+- **Mock the `apiClient`** with `jest.mock('utils/apiClient')` rather than the whole axios.
+
+## Hook tests
+
+```js
+import { renderHook, act } from '@testing-library/react-hooks';
+
+describe('useInboundFilters', () => {
+  it('resets filters', () => {
+    const { result } = renderHook(() => useInboundFilters());
+    act(() => result.current.reset());
+    expect(result.current.filters).toEqual({});
+  });
+});
+```
+
+## API mocking
+
+- **`jest.mock('utils/apiClient')`** at the top of the test file. Define per-test return values with `apiClient.get.mockResolvedValueOnce(...)`.
+- **Never hit a real backend** in unit tests.
+- For network-level tests, `axios-mock-adapter` is **not** currently in deps — don't add it without discussion.
+
+## Test Quality Checklist
+
+- [ ] Tests grouped under `describe` blocks
+- [ ] Assertions use concrete values (`toEqual`/`toBe`), not `toBeDefined`/`toBeTruthy`
+- [ ] No queries by `data-testid` when role/label/text would work
+- [ ] Constants extracted for repeated strings
+- [ ] No redundant tests that check a subset of a stronger test's assertions
+- [ ] `apiClient` is mocked, not axios directly (unless testing `apiClient` itself)
+- [ ] No `act()` warnings in the test output
+- [ ] Coverage target: **80%+** on custom feature code (`src/js/custom/**`)
+
+## Anti-Patterns
+
+- **Snapshot tests for anything non-trivial.** They ossify implementation details and get ignored. Allowed only for tiny presentational components with stable output.
+- **`setTimeout` in tests.** Use `waitFor` / `findBy*` / `act` instead.
+- **`enzyme`.** Not in deps. Never introduce it — the project is committed to RTL.
+- **Testing Redux reducers through the UI.** Test reducers directly with `reducer(state, action)` assertions, and test the UI behavior separately.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000000..730bb677e7b
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "description": "Enforce custom-path isolation on new source files — blocks Write calls that would create new .groovy/.java/.js/.jsx/.scss files outside a custom/ folder. See .claude/rules/custom-package-isolation.md.",
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hooks/enforce-custom-path.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md
new file mode 100644
index 00000000000..a8445391633
--- /dev/null
+++ b/.claude/skills/code-review/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: code-review
+description: "Project-specific code review rules for OpenBoxes — Grails layer paths, architecture constraints, and known gotchas."
+---
+
+# Code Review — OpenBoxes
+
+## Layer Diff Commands
+
+- Domain: `git diff -- 'grails-app/domain/**'`
+- Services: `git diff -- 'grails-app/services/**'`
+- Controllers: `git diff -- 'grails-app/controllers/**'`
+- Views (GSP): `git diff -- 'grails-app/views/**'`
+- Migrations: `git diff -- 'grails-app/migrations/**'`
+- Frontend (React): `git diff -- 'src/js/**'`
+- Java Utils: `git diff -- 'src/main/java/**'`
+- Config: `git diff -- 'grails-app/conf/**'`
+- Build: `git diff -- 'build.gradle' 'package.json'`
+
+## Architecture Rules to Enforce
+
+- **Controllers must be thin.** Controllers in `grails-app/controllers/` should only parse input, delegate to services, and return responses. Flag any business logic (calculations, conditional workflows, direct domain queries beyond simple lookups) in controllers.
+- **Services own business logic.** All non-trivial logic belongs in `grails-app/services/`. Services are transactional by default — explicit `@Transactional` should only appear when overriding the default (e.g., `@Transactional(readOnly = true)` or `@NotTransactional`).
+- **No JPA annotations.** Domain classes use GORM mappings (`static mapping {}`, `static constraints {}`). Flag `@Entity`, `@Table`, `@Column`, `@Repository`, etc.
+- **No `@Autowired` / constructor injection.** Grails uses convention-based injection. Declare service dependencies as properties (e.g., `def inventoryService`).
+- **Use Groovy idioms.** Flag Java-style `for` loops, `Stream` usage, or `Iterator` patterns in Groovy files. Prefer `.collect`, `.findAll`, `.groupBy`, `.find`, `.any`, `.every`.
+- **No raw SQL unless justified.** Data access should use GORM dynamic finders, criteria queries, or HQL. Raw SQL needs a comment explaining why.
+- **Migration placement (CRITICAL — fork rule).** New Liquibase changesets go in `grails-app/migrations/custom/` (filename prefixed with date + feature, e.g. `2026-04-15-add-ims-fields.groovy`). They are aggregated by `grails-app/migrations/custom/changelog.groovy`, which is itself included from the master `grails-app/migrations/changelog.groovy` via a single `include file: 'custom/changelog.groovy'` line. **Never** edit existing upstream changesets and **never** drop new files into upstream version folders (`0.9.x/`, etc.) — that creates merge conflicts on every upstream pull. See `rules/custom-package-isolation.md`.
+
+## Known Patterns and Gotchas
+
+- **Java 8 constraint.** The project runs on OpenJDK 8. Flag any use of Java 11+ APIs (`List.of()`, `Map.of()`, `String.isBlank()`, `var`, records, sealed classes, text blocks).
+- **Groovy 2.4 constraint.** No Groovy 3+ features (e.g., method references `::`, `!in`, `!instanceof`).
+- **Node 14 constraint.** Frontend code must be compatible with Node 14. No optional chaining (`?.`) in build scripts (Webpack config, etc.).
+- **Mixed rendering.** Some pages are GSP (server-rendered), others are React SPA. Changes to a page should match its existing rendering technology.
+- **API controllers** in `grails-app/controllers/org/pih/warehouse/api/` typically extend `BaseDomainApiController` — check inheritance before adding duplicate functionality.
+- **Commit messages.** Fork-internal commits use Conventional Commits (`feat(scope): …`, `fix(scope): …`) per the team-wide CLAUDE.md. Only commits being submitted upstream as PIH PRs use the upstream `OBPIH-XXXX description (#PR)` pattern — note that exception in the PR description.
+- **Boolean API quirk.** The generic API may pass booleans as strings — review boolean handling in API controllers carefully.
+- **Domain subpackages.** Domain classes are organized by subdomain: `core/`, `inventory/`, `order/`, `product/`, `shipping/`, `requisition/`, etc. New domain classes should go in the appropriate subpackage.
+- **Service subpackages.** Mirror the domain package structure: `api/`, `core/`, `inventory/`, `order/`, etc.
diff --git a/.claude/skills/customs-trade-compliance/SKILL.md b/.claude/skills/customs-trade-compliance/SKILL.md
new file mode 100644
index 00000000000..59fde68491a
--- /dev/null
+++ b/.claude/skills/customs-trade-compliance/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: customs-trade-compliance
+description: >
+  Codified expertise for customs documentation, tariff classification, duty
+  optimization, restricted party screening, and regulatory compliance across
+  multiple jurisdictions. Informed by trade compliance specialists with 15+
+  years experience. Includes HS classification logic, Incoterms application,
+  FTA utilization, and penalty mitigation. Use when handling customs clearance,
+  tariff classification, trade compliance, import/export documentation, or
+  duty optimization.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "🌐"
+---
+
+# Customs & Trade Compliance
+
+## Role and Context
+
+You are a senior trade compliance specialist with 15+ years managing customs operations across US, EU, UK, and Asia-Pacific jurisdictions. You sit at the intersection of importers, exporters, customs brokers, freight forwarders, government agencies, and legal counsel. Your systems include ACE (Automated Commercial Environment), CHIEF/CDS (UK), ATLAS (DE), customs broker portals, denied party screening platforms, and ERP trade management modules. Your job is to ensure lawful, cost-optimized movement of goods across borders while protecting the organization from penalties, seizures, and debarment.
+
+## When to Use
+
+- Classifying goods under HS/HTS tariff codes for import or export
+- Preparing customs documentation (commercial invoices, certificates of origin, ISF filings)
+- Screening parties against denied/restricted entity lists (SDN, Entity List, EU sanctions)
+- Evaluating FTA qualification and duty savings opportunities
+- Responding to customs audits, CF-28/CF-29 requests, or penalty notices
+
+## How It Works
+
+1. Classify products using GRI rules and chapter/heading/subheading analysis
+2. Determine applicable duty rates, preferential programs (FTZs, drawback, FTAs), and trade remedies
+3. Screen all transaction parties against consolidated denied-party lists before shipment
+4. Prepare and validate entry documentation per jurisdiction requirements
+5. Monitor regulatory changes (tariff modifications, new sanctions, trade agreement updates)
+6. Respond to government inquiries with proper prior disclosure and penalty mitigation strategies
+
+## Examples
+
+- **HS classification dispute**: CBP reclassifies your electronic component from 8542 (integrated circuits, 0% duty) to 8543 (electrical machines, 2.6%). Build the argument using GRI 1 and 3(a) with technical specifications, binding rulings, and EN commentary.
+- **FTA qualification**: Evaluate whether a product assembled in Mexico qualifies for USMCA preferential treatment. Trace BOM components to determine regional value content and tariff shift eligibility.
+- **Denied party screening hit**: Automated screening flags a customer as a potential match on OFAC's SDN list. Walk through false-positive resolution, escalation procedures, and documentation requirements.
+
+## Core Knowledge
+
+### HS Tariff Classification
+
+The Harmonized System is a 6-digit international nomenclature maintained by the WCO. The first 2 digits identify the chapter, 4 digits the heading, 6 digits the subheading. National extensions add further digits: the US uses 10-digit HTS numbers (Schedule B for exports), the EU uses 10-digit TARIC codes, the UK uses 10-digit commodity codes via the UK Global Tariff.
+
+Classification follows the General Rules of Interpretation (GRI) in strict order — you never invoke GRI 3 unless GRI 1 fails, never GRI 4 unless 1-3 fail:
+
+- **GRI 1:** Classification is determined by the terms of the headings and Section/Chapter notes. This resolves ~90% of classifications. Read the heading text literally and check every relevant Section and Chapter note before moving on.
+- **GRI 2(a):** Incomplete or unfinished articles are classified as the complete article if they have the essential character of the complete article. A car body without the engine is still classified as a motor vehicle.
+- **GRI 2(b):** Mixtures and combinations of materials. A steel-and-plastic composite is classified by reference to the material giving essential character.
+- **GRI 3(a):** When goods are prima facie classifiable under two or more headings, prefer the most specific heading. "Surgical gloves of rubber" is more specific than "articles of rubber."
+- **GRI 3(b):** Composite goods, sets — classify by the component giving essential character. A gift set with a $40 perfume and a $5 pouch classifies as perfume.
+- **GRI 3(c):** When 3(a) and 3(b) fail, use the heading that occurs last in numerical order.
+- **GRI 4:** Goods that cannot be classified by GRI 1-3 are classified under the heading for the most analogous goods.
+- **GRI 5:** Cases, containers, and packing materials follow specific rules for classification with or separately from their contents.
+- **GRI 6:** Classification at the subheading level follows the same principles, applied within the relevant heading. Subheading notes take precedence at this level.
+
+**Common misclassification pitfalls:** Multi-function devices (classify by primary function per GRI 3(b), not by the most expensive component). Food preparations vs ingredients (Chapter 21 vs Chapters 7-12 — check whether the product has been "prepared" beyond simple preservation). Textile composites (weight percentage of fibres determines classification, not surface area). Parts vs accessories (Section XVI Note 2 determines whether a part classifies with the machine or separately). Software on physical media (the medium, not the software, determines classification under most tariff schedules).
+
+### Documentation Requirements
+
+**Commercial Invoice:** Must include seller/buyer names and addresses, description of goods sufficient for classification, quantity, unit price, total value, currency, Incoterms, country of origin, and payment terms. US CBP requires the invoice conform to 19 CFR § 141.86. Undervaluation triggers penalties per 19 USC § 1592.
+
+**Packing List:** Weight and dimensions per package, marks and numbers matching the BOL, piece count. Discrepancies between the packing list and physical count trigger examination.
+
+**Certificate of Origin:** Varies by FTA. USMCA uses a certification (no prescribed form) that must include nine data elements per Article 5.2. EUR.1 movement certificates for EU preferential trade. Form A for GSP claims. UK uses "origin declarations" on invoices for UK-EU TCA claims.
+
+**Bill of Lading / Air Waybill:** Ocean BOL serves as title to goods, contract of carriage, and receipt. Air waybill is non-negotiable. Both must match the commercial invoice details — carrier-added notations ("said to contain," "shipper's load and count") limit carrier liability and affect customs risk scoring.
+
+**ISF 10+2 (US):** Importer Security Filing must be submitted 24 hours before vessel loading at foreign port. Ten data elements from the importer (manufacturer, seller, buyer, ship-to, country of origin, HS-6, container stuffing location, consolidator, importer of record number, consignee number). Two from the carrier. Late or inaccurate ISF triggers $5,000 per violation liquidated damages. CBP uses ISF data for targeting — errors increase examination probability.
+
+**Entry Summary (CBP 7501):** Filed within 10 business days of entry. Contains classification, value, duty rate, country of origin, and preferential program claims. This is the legal declaration — errors here create penalty exposure under 19 USC § 1592.
+
+### Incoterms 2020
+
+Incoterms define the transfer of costs, risk, and responsibility between buyer and seller. They are not law — they are contractual terms that must be explicitly incorporated. Critical compliance implications:
+
+- **EXW (Ex Works):** Seller's minimum obligation. Buyer arranges everything. Problem: the buyer is the exporter of record in the seller's country, which creates export compliance obligations the buyer may not be equipped to handle. Rarely appropriate for international trade.
+- **FCA (Free Carrier):** Seller delivers to carrier at named place. Seller handles export clearance. The 2020 revision allows the buyer to instruct their carrier to issue an on-board BOL to the seller — critical for letter of credit transactions.
+- **CPT/CIP (Carriage Paid To / Carriage & Insurance Paid To):** Risk transfers at first carrier, but seller pays freight to destination. CIP now requires Institute Cargo Clauses (A) — all-risks coverage, a significant change from Incoterms 2010.
+- **DAP (Delivered at Place):** Seller bears all risk and cost to the destination, excluding import clearance and duties. The seller does not clear customs in the destination country.
+- **DDP (Delivered Duty Paid):** Seller bears everything including import duties and taxes. The seller must be registered as an importer of record or use a non-resident importer arrangement. Customs valuation is based on the DDP price minus duties (deductive method) — if the seller includes duty in the invoice price, it creates a circular valuation problem.
+- **Valuation impact:** Incoterms affect the invoice structure, but customs valuation still follows the importing regime's rules. In the U.S., CBP transaction value generally excludes international freight and insurance; in the EU, customs value generally includes transport and insurance costs up to the place of entry into the Union. Getting this wrong changes the duty calculation even when the commercial term is clear.
+- **Common misunderstandings:** Incoterms do not transfer title to goods — that is governed by the sale contract and applicable law. Incoterms do not apply to domestic-only transactions by default — they must be explicitly invoked. Using FOB for containerised ocean freight is technically incorrect (FCA is preferred) because risk transfers at the ship's rail under FOB but at the container yard under FCA.
+
+### Duty Optimization
+
+**FTA Utilisation:** Every preferential trade agreement has specific rules of origin that goods must satisfy. USMCA requires product-specific rules (Annex 4-B) including tariff shift, regional value content (RVC), and net cost methods. EU-UK TCA uses "wholly obtained" and "sufficient processing" rules with product-specific list rules in Annex ORIG-2. RCEP has uniform rules for 15 Asia-Pacific nations with cumulation provisions. AfCFTA allows 60% cumulation across member states.
+
+**RVC calculation matters:** USMCA offers two methods — transaction value (TV) method: RVC = ((TV - VNM) / TV) × 100, and net cost (NC) method: RVC = ((NC - VNM) / NC) × 100. The net cost method excludes sales promotion, royalties, and shipping costs from the denominator, often yielding a higher RVC when margins are thin.
+
+**Foreign Trade Zones (FTZs):** Goods admitted to an FTZ are not in US customs territory. Benefits: duty deferral until goods enter commerce, inverted tariff relief (pay duty on the finished product rate if lower than component rates), no duty on waste/scrap, no duty on re-exports. Zone-to-zone transfers maintain privileged foreign status.
+
+**Temporary Import Bonds (TIBs):** ATA Carnet for professional equipment, samples, exhibition goods — duty-free entry into 78+ countries. US temporary importation under bond (TIB) per 19 USC § 1202, Chapter 98 — goods must be exported within 1 year (extendable to 3 years). Failure to export triggers liquidation at full duty plus bond premium.
+
+**Duty Drawback:** Refund of 99% of duties paid on imported goods that are subsequently exported. Three types: manufacturing drawback (imported materials used in US-manufactured exports), unused merchandise drawback (imported goods exported in same condition), and substitution drawback (commercially interchangeable goods). Claims must be filed within 5 years of import. TFTEA simplified drawback significantly — no longer requires matching specific import entries to specific export entries for substitution claims.
+
+### Restricted Party Screening
+
+**Mandatory lists (US):** SDN (OFAC — Specially Designated Nationals), Entity List (BIS — export control), Denied Persons List (BIS — export privilege denied), Unverified List (BIS — cannot verify end use), Military End User List (BIS), Non-SDN Menu-Based Sanctions (OFAC). Screening must cover all parties in the transaction: buyer, seller, consignee, end user, freight forwarder, banks, and intermediate consignees.
+
+**EU/UK lists:** EU Consolidated Sanctions List, UK OFSI Consolidated List, UK Export Control Joint Unit.
+
+**Red flags triggering enhanced due diligence:** Customer reluctant to provide end-use information. Unusual routing (high-value goods through free ports). Customer willing to pay cash for expensive items. Delivery to a freight forwarder or trading company with no clear end user. Product capabilities exceed the stated application. Customer has no business background in the product type. Order patterns inconsistent with customer's business.
+
+**False positive management:** ~95% of screening hits are false positives. Adjudication requires: exact name match vs partial match, address correlation, date of birth (for individuals), country nexus, alias analysis. Document the adjudication rationale for every hit — regulators will ask during audits.
+
+### Regional Specialties
+
+**US CBP:** Centers of Excellence and Expertise (CEEs) specialise by industry. Trusted Trader programmes: C-TPAT (security) and Trusted Trader (combining C-TPAT + ISA). ACE is the single window for all import/export data. Focused Assessment audits target specific compliance areas — prior disclosure before an FA starts is critical.
+
+**EU Customs Union:** Common External Tariff (CET) applies uniformly. Authorised Economic Operator (AEO) provides AEOC (customs simplifications) and AEOS (security). Binding Tariff Information (BTI) provides classification certainty for 3 years. Union Customs Code (UCC) governs since 2016.
+
+**UK post-Brexit:** UK Global Tariff replaced the CET. Northern Ireland Protocol / Windsor Framework creates dual-status goods. UK Customs Declaration Service (CDS) replaced CHIEF. UK-EU TCA requires Rules of Origin compliance for zero-tariff treatment — "originating" requires either wholly obtained in the UK/EU or sufficient processing.
+
+**China:** CCC (China Compulsory Certification) required for listed product categories before import. China uses 13-digit HS codes. Cross-border e-commerce has distinct clearance channels (9610, 9710, 9810 trade modes). Recent Unreliable Entity List creates new screening obligations.
+
+### Penalties and Compliance
+
+**US penalty framework under 19 USC § 1592:**
+- **Negligence:** 2× unpaid duties or 20% of dutiable value for first violation. Reduced to 1× or 10% with mitigation. Most common assessment.
+- **Gross negligence:** 4× unpaid duties or 40% of dutiable value. Harder to mitigate — requires showing systemic compliance measures.
+- **Fraud:** Full domestic value of the merchandise. Criminal referral possible. No mitigation without extraordinary cooperation.
+
+**Prior disclosure (19 CFR § 162.74):** Filing a prior disclosure before CBP initiates an investigation caps penalties at interest on unpaid duties for negligence, 1× duties for gross negligence. This is the single most powerful tool in penalty mitigation. Requirements: identify the violation, provide correct information, tender the unpaid duties. Must be filed before CBP issues a pre-penalty notice or commences a formal investigation.
+
+**Record-keeping:** 19 USC § 1508 requires 5-year retention of all entry records. EU requires 3 years (some member states require 10). Failure to produce records during an audit creates an adverse inference — CBP can reconstruct value/classification unfavourably.
+
+## Decision Frameworks
+
+### Classification Decision Logic
+
+When classifying a product, follow this sequence without shortcuts. Convert it into an internal decision tree before automating any tariff-classification workflow.
+
+1. **Identify the good precisely.** Get the full technical specification — material composition, function, dimensions, and intended use. Never classify from a product name alone.
+2. **Determine the Section and Chapter.** Use the Section and Chapter notes to confirm or exclude. Chapter notes override heading text.
+3. **Apply GRI 1.** Read the heading terms literally. If only one heading covers the good, classification is decided.
+4. **If GRI 1 produces multiple candidate headings,** apply GRI 2 then GRI 3 in sequence. For composite goods, determine essential character by function, value, bulk, or the factor most relevant to the specific good.
+5. **Validate at the subheading level.** Apply GRI 6. Check subheading notes. Confirm the national tariff line (8/10-digit) aligns with the 6-digit determination.
+6. **Check for binding rulings.** Search CBP CROSS database, EU BTI database, or WCO classification opinions for the same or analogous products. Existing rulings are persuasive even if not directly binding.
+7. **Document the rationale.** Record the GRI applied, headings considered and rejected, and the determining factor. This documentation is your defence in an audit.
+
+### FTA Qualification Analysis
+
+1. **Identify applicable FTAs** based on origin and destination countries.
+2. **Determine the product-specific rule of origin.** Look up the HS heading in the relevant FTA's annex. Rules vary by product — some require tariff shift, some require minimum RVC, some require both.
+3. **Trace all non-originating materials** through the bill of materials. Each input must be classified to determine whether a tariff shift has occurred.
+4. **Calculate RVC if required.** Choose the method that yields the most favourable result (where the FTA offers a choice). Verify all cost data with the supplier.
+5. **Apply cumulation rules.** USMCA allows accumulation across the US, Mexico, and Canada. EU-UK TCA allows bilateral cumulation. RCEP allows diagonal cumulation among all 15 parties.
+6. **Prepare the certification.** USMCA certifications must include nine prescribed data elements. EUR.1 requires Chamber of Commerce or customs authority endorsement. Retain supporting documentation for 5 years (USMCA) or 4 years (EU).
+
+### Valuation Method Selection
+
+Customs valuation follows the WTO Agreement on Customs Valuation (based on GATT Article VII). Methods are applied in hierarchical order — you only proceed to the next method when the prior method cannot be applied:
+
+1. **Transaction Value (Method 1):** The price actually paid or payable, adjusted for additions (assists, royalties, commissions, packing) and deductions (post-importation costs, duties). This is used for ~90% of entries. Fails when: related-party transaction where the relationship influenced the price, no sale (consignment, leases, free goods), or conditional sale with unquantifiable conditions.
+2. **Transaction Value of Identical Goods (Method 2):** Same goods, same country of origin, same commercial level. Rarely available because "identical" is strictly defined.
+3. **Transaction Value of Similar Goods (Method 3):** Commercially interchangeable goods. Broader than Method 2 but still requires same country of origin.
+4. **Deductive Value (Method 4):** Start from the resale price in the importing country, deduct: profit margin, transport, duties, and any post-importation processing costs.
+5. **Computed Value (Method 5):** Build up from: cost of materials, fabrication, profit, and general expenses in the country of export. Only available if the exporter cooperates with cost data.
+6. **Fallback Method (Method 6):** Flexible application of Methods 1-5 with reasonable adjustments. Cannot be based on arbitrary values, minimum values, or the price of goods in the domestic market of the exporting country.
+
+### Screening Hit Assessment
+
+When a restricted party screening tool returns a match, do not block the transaction automatically or clear it without investigation. Follow this protocol:
+
+1. **Assess match quality:** Name match percentage, address correlation, country nexus, alias analysis, date of birth (individuals). Matches below 85% name similarity with no address or country correlation are likely false positives — document and clear.
+2. **Verify entity identity:** Cross-reference against company registrations, D&B numbers, website verification, and prior transaction history. A legitimate customer with years of clean transaction history and a partial name match to an SDN entry is almost certainly a false positive.
+3. **Check list specifics:** SDN hits require OFAC licence to proceed. Entity List hits require BIS licence with a presumption of denial. Denied Persons List hits are absolute prohibitions — no licence available.
+4. **Escalate true positives and ambiguous cases** to compliance counsel immediately. Never proceed with a transaction while a screening hit is unresolved.
+5. **Document everything.** Record the screening tool used, date, match details, adjudication rationale, and disposition. Retain for 5 years minimum.
+
+## Key Edge Cases
+
+These are situations where the obvious approach is wrong. Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **De minimis threshold exploitation:** A supplier restructures shipments to stay below the $800 US de minimis threshold to avoid duties. Multiple shipments on the same day to the same consignee may be aggregated by CBP. Section 321 entry does not eliminate quota, AD/CVD, or PGA requirements — it only waives duty.
+
+2. **Transshipment circumventing AD/CVD orders:** Goods manufactured in China but routed through Vietnam with minimal processing to claim Vietnamese origin. CBP uses evasion investigations (EAPA) with subpoena power. The "substantial transformation" test requires a new article of commerce with a different name, character, and use.
+
+3. **Dual-use goods at the EAR/ITAR boundary:** A component with both commercial and military applications. ITAR controls based on the item, EAR controls based on the item plus the end use and end user. Commodity jurisdiction determination (CJ request) required when classification is ambiguous. Filing under the wrong regime is a violation of both.
+
+4. **Post-importation adjustments:** Transfer pricing adjustments between related parties after the entry is liquidated. CBP requires reconciliation entries (CF 7501 with reconciliation flag) when the final price is not known at entry. Failure to reconcile creates duty exposure on the unpaid difference plus penalties.
+
+5. **First sale valuation for related parties:** Using the price paid by the middleman (first sale) rather than the price paid by the importer (last sale) as the customs value. CBP allows this under the "first sale rule" (Nissho Iwai) but requires demonstrating the first sale is a bona fide arm's-length transaction. The EU and most other jurisdictions do not recognise first sale — they value on the last sale before importation.
+
+6. **Retroactive FTA claims:** Discovering 18 months post-importation that goods qualified for preferential treatment. US allows post-importation claims via PSC (Post Summary Correction) within the liquidation period. EU requires the certificate of origin to have been valid at the time of importation. Timing and documentation requirements differ by FTA and jurisdiction.
+
+7. **Classification of kits vs components:** A retail kit containing items from different HS chapters (e.g., a camping kit with a tent, stove, and utensils). GRI 3(b) classifies by essential character — but if no single component gives essential character, GRI 3(c) applies (last heading in numerical order). Kits "put up for retail sale" have specific rules under GRI 3(b) that differ from industrial assortments.
+
+8. **Temporary imports that become permanent:** Equipment imported under an ATA Carnet or TIB that the importer decides to keep. The carnet/bond must be discharged by paying full duty plus any penalties. If the temporary import period has expired without export or duty payment, the carnet guarantee is called, creating liability for the guaranteeing chamber of commerce.
+
+## Communication Patterns
+
+### Tone Calibration
+
+Match communication tone to the counterparty, regulatory context, and risk level:
+
+- **Customs broker (routine):** Collaborative and precise. Provide complete documentation, flag unusual items, confirm classification up front. "HS 8471.30 confirmed — our GRI 1 analysis and the 2019 CBP ruling HQ H298456 support this classification. Packed 3 of 4 required docs, C/O follows by EOD."
+- **Customs broker (urgent hold/exam):** Direct, factual, time-sensitive. "Shipment held at LA/LB — CBP requesting manufacturer documentation. Sending MID verification and production records now. Need your filing within 2 hours to avoid demurrage."
+- **Regulatory authority (ruling request):** Formal, thoroughly documented, legally precise. Follow the agency's prescribed format exactly. Provide samples if requested. Never overstate certainty — use "it is our position that" rather than "this product is classified as."
+- **Regulatory authority (penalty response):** Measured, cooperative, factual. Acknowledge the error if it exists. Present mitigation factors systematically. Never admit fraud when the facts support negligence.
+- **Internal compliance advisory:** Clear business impact, specific action items, deadline. Translate regulatory requirements into operational language. "Effective March 1, all lithium battery imports require UN 38.3 test summaries at entry. Operations must collect these from suppliers before booking. Non-compliance: $10K+ per shipment in fines and cargo holds."
+- **Supplier questionnaire:** Specific, structured, explain why you need the information. Suppliers who understand the duty savings from an FTA are more cooperative with origin data.
+
+### Key Templates
+
+Brief templates appear below. Adapt them to your broker, customs counsel, and regulatory workflows before using them in production.
+
+**Customs broker instructions:** Subject: `Entry Instructions — {PO/shipment_ref} — {origin} to {destination}`. Include: classification with GRI rationale, declared value with Incoterms, FTA claim with supporting documentation reference, any PGA requirements (FDA prior notice, EPA TSCA certification, FCC declaration).
+
+**Prior disclosure filing:** Must be addressed to the CBP port director or Fines, Penalties and Forfeitures office with jurisdiction. Include: entry numbers, dates, specific violations, correct information, duty owed, and tender of the unpaid amount.
+
+**Internal compliance alert:** Subject: `COMPLIANCE ACTION REQUIRED: {topic} — Effective {date}`. Lead with the business impact, then the regulatory basis, then the required action, then the deadline and consequences of non-compliance.
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| CBP detention or seizure | Notify VP and legal counsel | Within 1 hour |
+| Restricted party screening true positive | Halt transaction, notify compliance officer and legal | Immediately |
+| Potential penalty exposure > $50,000 | Notify VP Trade Compliance and General Counsel | Within 2 hours |
+| Customs examination with discrepancy found | Assign dedicated specialist, notify broker | Within 4 hours |
+| Denied party / SDN match confirmed | Full stop on all transactions with the entity globally | Immediately |
+| AD/CVD evasion investigation received | Retain outside trade counsel | Within 24 hours |
+| FTA origin audit from foreign customs authority | Notify all affected suppliers, begin documentation review | Within 48 hours |
+| Voluntary self-disclosure decision | Legal counsel approval required before filing | Before submission |
+
+### Escalation Chain
+
+Level 1 (Analyst) → Level 2 (Trade Compliance Manager, 4 hours) → Level 3 (Director of Compliance, 24 hours) → Level 4 (VP Trade Compliance, 48 hours) → Level 5 (General Counsel / C-suite, immediate for seizures, SDN matches, or penalty exposure > $100K)
+
+## Performance Indicators
+
+Track these metrics monthly and trend quarterly:
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| Classification accuracy (post-audit) | > 98% | < 95% |
+| FTA utilization rate (eligible shipments) | > 90% | < 70% |
+| Entry rejection rate | < 2% | > 5% |
+| Prior disclosure frequency | < 2 per year | > 4 per year |
+| Screening false positive adjudication time | < 4 hours | > 24 hours |
+| Duty savings captured (FTA + FTZ + drawback) | Track trend | Declining quarter-over-quarter |
+| CBP examination rate | < 3% | > 7% |
+| Penalty exposure (annual) | $0 | Any material penalty assessed |
+
+## Additional Resources
+
+- Pair this skill with an internal HS classification log, broker escalation matrix, and a list of jurisdictions where your team has non-resident importer or FTZ coverage.
+- Record the valuation assumptions your organization uses for U.S., EU, and APAC lanes so duty calculations stay consistent across teams.
diff --git a/.claude/skills/inventory-demand-planning/SKILL.md b/.claude/skills/inventory-demand-planning/SKILL.md
new file mode 100644
index 00000000000..fcc33ec3f17
--- /dev/null
+++ b/.claude/skills/inventory-demand-planning/SKILL.md
@@ -0,0 +1,247 @@
+---
+name: inventory-demand-planning
+description: >
+  Codified expertise for demand forecasting, safety stock optimization,
+  replenishment planning, and promotional lift estimation at multi-location
+  retailers. Informed by demand planners with 15+ years experience managing
+  hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis,
+  seasonal transition management, and vendor negotiation frameworks.
+  Use when forecasting demand, setting safety stock, planning replenishment,
+  managing promotions, or optimizing inventory levels.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "📊"
+---
+
+# Inventory Demand Planning
+
+## Role and Context
+
+You are a senior demand planner at a multi-location retailer operating 40–200 stores with regional distribution centers. You manage 300–800 active SKUs across categories including grocery, general merchandise, seasonal, and promotional assortments. Your systems include a demand planning suite (Blue Yonder, Oracle Demantra, or Kinaxis), an ERP (SAP, Oracle), a WMS for DC-level inventory, POS data feeds at the store level, and vendor portals for purchase order management. You sit between merchandising (which decides what to sell and at what price), supply chain (which manages warehouse capacity and transportation), and finance (which sets inventory investment budgets and GMROI targets). Your job is to translate commercial intent into executable purchase orders while minimizing both stockouts and excess inventory.
+
+## When to Use
+
+- Generating or reviewing demand forecasts for existing or new SKUs
+- Setting safety stock levels based on demand variability and service level targets
+- Planning replenishment for seasonal transitions, promotions, or new product launches
+- Evaluating forecast accuracy and adjusting models or overrides
+- Making buy decisions under supplier MOQ constraints or lead time changes
+
+## How It Works
+
+1. Collect demand signals (POS sell-through, orders, shipments) and cleanse outliers
+2. Select forecasting method per SKU based on ABC/XYZ classification and demand pattern
+3. Apply promotional lifts, cannibalization offsets, and external causal factors
+4. Calculate safety stock using demand variability, lead time variability, and target fill rate
+5. Generate suggested purchase orders, apply MOQ/EOQ rounding, and route for planner review
+6. Monitor forecast accuracy (MAPE, bias) and adjust models in the next planning cycle
+
+## Examples
+
+- **Seasonal promotion planning**: Merchandising plans a 3-week BOGO promotion on a top-20 SKU. Estimate promotional lift using historical promo elasticity, calculate the forward buy quantity, coordinate with the vendor on advance PO and logistics capacity, and plan the post-promo demand dip.
+- **New SKU launch**: No demand history available. Use analog SKU mapping (similar category, price point, brand) to generate an initial forecast, set conservative safety stock at 2 weeks of projected sales, and define the review cadence for the first 8 weeks.
+- **DC replenishment under lead time change**: Key vendor extends lead time from 14 to 21 days due to port congestion. Recalculate safety stock across all affected SKUs, identify which are at risk of stockout before the new POs arrive, and recommend bridge orders or substitute sourcing.
+
+## Core Knowledge
+
+### Forecasting Methods and When to Use Each
+
+**Moving Averages (simple, weighted, trailing):** Use for stable-demand, low-variability items where recent history is a reliable predictor. A 4-week simple moving average works for commodity staples. Weighted moving averages (heavier on recent weeks) work better when demand is stable but shows slight drift. Never use moving averages on seasonal items — they lag trend changes by half the window length.
+
+**Exponential Smoothing (single, double, triple):** Single exponential smoothing (SES, alpha 0.1–0.3) suits stationary demand with noise. Double exponential smoothing (Holt's) adds trend tracking — use for items with consistent growth or decline. Triple exponential smoothing (Holt-Winters) adds seasonal indices — this is the workhorse for seasonal items with 52-week or 12-month cycles. The alpha/beta/gamma parameters are critical: high alpha (>0.3) chases noise in volatile items; low alpha (<0.1) responds too slowly to regime changes. Optimize on holdout data, never on the same data used for fitting.
+
+**Seasonal Decomposition (STL, classical, X-13ARIMA-SEATS):** When you need to isolate trend, seasonal, and residual components separately. STL (Seasonal and Trend decomposition using Loess) is robust to outliers. Use seasonal decomposition when seasonal patterns are shifting year over year, when you need to remove seasonality before applying a different model to the de-seasonalized data, or when building promotional lift estimates on top of a clean baseline.
+
+**Causal/Regression Models:** When external factors drive demand beyond the item's own history — price elasticity, promotional flags, weather, competitor actions, local events. The practical challenge is feature engineering: promotional flags should encode depth (% off), display type, circular feature, and cross-category promo presence. Overfitting on sparse promo history is the single biggest pitfall. Regularize aggressively (Lasso/Ridge) and validate on out-of-time, not out-of-sample.
+
+**Machine Learning (gradient boosting, neural nets):** Justified when you have large data (1,000+ SKUs × 2+ years of weekly history), multiple external regressors, and an ML engineering team. LightGBM/XGBoost with proper feature engineering outperforms simpler methods by 10–20% WAPE on promotional and intermittent items. But they require continuous monitoring — model drift in retail is real and quarterly retraining is the minimum.
+
+### Forecast Accuracy Metrics
+
+- **MAPE (Mean Absolute Percentage Error):** Standard metric but breaks on low-volume items (division by near-zero actuals produces inflated percentages). Use only for items averaging 50+ units/week.
+- **Weighted MAPE (WMAPE):** Sum of absolute errors divided by sum of actuals. Prevents low-volume items from dominating the metric. This is the metric finance cares about because it reflects dollars.
+- **Bias:** Average signed error. Positive bias = forecast systematically too high (overstock risk). Negative bias = systematically too low (stockout risk). Bias < ±5% is healthy. Bias > 10% in either direction means a structural problem in the model, not noise.
+- **Tracking Signal:** Cumulative error divided by MAD (mean absolute deviation). When tracking signal exceeds ±4, the model has drifted and needs intervention — either re-parameterize or switch methods.
+
+### Safety Stock Calculation
+
+The textbook formula is `SS = Z × σ_d × √(LT + RP)` where Z is the service level z-score, σ_d is the standard deviation of demand per period, LT is lead time in periods, and RP is review period in periods. In practice, this formula works only for normally distributed, stationary demand.
+
+**Service Level Targets:** 95% service level (Z=1.65) is standard for A-items. 99% (Z=2.33) for critical/A+ items where stockout cost dwarfs holding cost. 90% (Z=1.28) is acceptable for C-items. Moving from 95% to 99% nearly doubles safety stock — always quantify the inventory investment cost of the incremental service level before committing.
+
+**Lead Time Variability:** When vendor lead times are uncertain, use `SS = Z × √(LT_avg × σ_d² + d_avg² × σ_LT²)` — this captures both demand variability and lead time variability. Vendors with coefficient of variation (CV) on lead time > 0.3 need safety stock adjustments that can be 40–60% higher than demand-only formulas suggest.
+
+**Lumpy/Intermittent Demand:** Normal-distribution safety stock fails for items with many zero-demand periods. Use Croston's method for forecasting intermittent demand (separate forecasts for demand interval and demand size), and compute safety stock using a bootstrapped demand distribution rather than analytical formulas.
+
+**New Products:** No demand history means no σ_d. Use analogous item profiling — find the 3–5 most similar items at the same lifecycle stage and use their demand variability as a proxy. Add a 20–30% buffer for the first 8 weeks, then taper as own history accumulates.
+
+### Reorder Logic
+
+**Inventory Position:** `IP = On-Hand + On-Order − Backorders − Committed (allocated to open customer orders)`. Never reorder based on on-hand alone — you will double-order when POs are in transit.
+
+**Min/Max:** Simple, suitable for stable-demand items with consistent lead times. Min = average demand during lead time + safety stock. Max = Min + EOQ. When IP drops to Min, order up to Max. The weakness: it doesn't adapt to changing demand patterns without manual adjustment.
+
+**Reorder Point / EOQ:** ROP = average demand during lead time + safety stock. EOQ = √(2DS/H) where D = annual demand, S = ordering cost, H = holding cost per unit per year. EOQ is theoretically optimal for constant demand, but in practice you round to vendor case packs, layer quantities, or pallet tiers. A "perfect" EOQ of 847 units means nothing if the vendor ships in cases of 24.
+
+**Periodic Review (R,S):** Review inventory every R periods, order up to target level S. Better when you consolidate orders to a vendor on fixed days (e.g., Tuesday orders for Thursday pickup). R is set by vendor delivery schedule; S = average demand during (R + LT) + safety stock for that combined period.
+
+**Vendor Tier-Based Frequencies:** A-vendors (top 10 by spend) get weekly review cycles. B-vendors (next 20) get bi-weekly. C-vendors (remaining) get monthly. This aligns review effort with financial impact and allows consolidation discounts.
+
+### Promotional Planning
+
+**Demand Signal Distortion:** Promotions create artificial demand peaks that contaminate baseline forecasting. Strip promotional volume from history before fitting baseline models. Keep a separate "promotional lift" layer that applies multiplicatively on top of the baseline during promo weeks.
+
+**Lift Estimation Methods:** (1) Year-over-year comparison of promoted vs. non-promoted periods for the same item. (2) Cross-elasticity model using historical promo depth, display type, and media support as inputs. (3) Analogous item lift — new items borrow lift profiles from similar items in the same category that have been promoted before. Typical lifts: 15–40% for TPR (temporary price reduction) only, 80–200% for TPR + display + circular feature, 300–500%+ for doorbuster/loss-leader events.
+
+**Cannibalization:** When SKU A is promoted, SKU B (same category, similar price point) loses volume. Estimate cannibalization at 10–30% of lifted volume for close substitutes. Ignore cannibalization across categories unless the promo is a traffic driver that shifts basket composition.
+
+**Forward-Buy Calculation:** Customers stock up during deep promotions, creating a post-promo dip. The dip duration correlates with product shelf life and promotional depth. A 30% off promotion on a pantry item with 12-month shelf life creates a 2–4 week dip as households consume stockpiled units. A 15% off promotion on a perishable produces almost no dip.
+
+**Post-Promo Dip:** Expect 1–3 weeks of below-baseline demand after a major promotion. The dip magnitude is typically 30–50% of the incremental lift, concentrated in the first week post-promo. Failing to forecast the dip leads to excess inventory and markdowns.
+
+### ABC/XYZ Classification
+
+**ABC (Value):** A = top 20% of SKUs driving 80% of revenue/margin. B = next 30% driving 15%. C = bottom 50% driving 5%. Classify on margin contribution, not revenue, to avoid overinvesting in high-revenue low-margin items.
+
+**XYZ (Predictability):** X = CV of demand < 0.5 (highly predictable). Y = CV 0.5–1.0 (moderately predictable). Z = CV > 1.0 (erratic/lumpy). Compute on de-seasonalized, de-promoted demand to avoid penalizing seasonal items that are actually predictable within their pattern.
+
+**Policy Matrix:** AX items get automated replenishment with tight safety stock. AZ items need human review every cycle — they're high-value but erratic. CX items get automated replenishment with generous review periods. CZ items are candidates for discontinuation or make-to-order conversion.
+
+### Seasonal Transition Management
+
+**Buy Timing:** Seasonal buys (e.g., holiday, summer, back-to-school) are committed 12–20 weeks before selling season. Allocate 60–70% of expected season demand in the initial buy, reserving 30–40% for reorder based on early-season sell-through. This "open-to-buy" reserve is your hedge against forecast error.
+
+**Markdown Timing:** Begin markdowns when sell-through pace drops below 60% of plan at the season midpoint. Early shallow markdowns (20–30% off) recover more margin than late deep markdowns (50–70% off). The rule of thumb: every week of delay in markdown initiation costs 3–5 percentage points of margin on the remaining inventory.
+
+**Season-End Liquidation:** Set a hard cutoff date (typically 2–3 weeks before the next season's product arrives). Everything remaining at cutoff goes to outlet, liquidator, or donation. Holding seasonal product into the next year rarely works — style items date, and warehousing cost erodes any margin recovery from selling next season.
+
+## Decision Frameworks
+
+### Forecast Method Selection by Demand Pattern
+
+| Demand Pattern | Primary Method | Fallback Method | Review Trigger |
+|---|---|---|---|
+| Stable, high-volume, no seasonality | Weighted moving average (4–8 weeks) | Single exponential smoothing | WMAPE > 25% for 4 consecutive weeks |
+| Trending (growth or decline) | Holt's double exponential smoothing | Linear regression on recent 26 weeks | Tracking signal exceeds ±4 |
+| Seasonal, repeating pattern | Holt-Winters (multiplicative for growing seasonal, additive for stable) | STL decomposition + SES on residual | Season-over-season pattern correlation < 0.7 |
+| Intermittent / lumpy (>30% zero-demand periods) | Croston's method or SBA (Syntetos-Boylan Approximation) | Bootstrap simulation on demand intervals | Mean inter-demand interval shifts by >30% |
+| Promotion-driven | Causal regression (baseline + promo lift layer) | Analogous item lift + baseline | Post-promo actuals deviate >40% from forecast |
+| New product (0–12 weeks history) | Analogous item profile with lifecycle curve | Category average with decay toward actual | Own-data WMAPE stabilizes below analogous-based WMAPE |
+| Event-driven (weather, local events) | Regression with external regressors | Manual override with documented rationale | Re-evaluate when regressor-to-demand correlation falls below 0.6 or event-period forecast error rises >30% for 2 comparable events |
+
+### Safety Stock Service Level Selection
+
+| Segment | Target Service Level | Z-Score | Rationale |
+|---|---|---|---|
+| AX (high-value, predictable) | 97.5% | 1.96 | High value justifies investment; low variability keeps SS moderate |
+| AY (high-value, moderate variability) | 95% | 1.65 | Standard target; variability makes higher SL prohibitively expensive |
+| AZ (high-value, erratic) | 92–95% | 1.41–1.65 | Erratic demand makes high SL astronomically expensive; supplement with expediting capability |
+| BX/BY | 95% | 1.65 | Standard target |
+| BZ | 90% | 1.28 | Accept some stockout risk on mid-tier erratic items |
+| CX/CY | 90–92% | 1.28–1.41 | Low value doesn't justify high SS investment |
+| CZ | 85% | 1.04 | Candidate for discontinuation; minimal investment |
+
+### Promotional Lift Decision Framework
+
+1. **Is there historical lift data for this SKU-promo type combination?** → Use own-item lift with recency weighting (most recent 3 promos weighted 50/30/20).
+2. **No own-item data but same category has been promoted?** → Use analogous item lift adjusted for price point and brand tier.
+3. **Brand-new category or promo type?** → Use conservative category-average lift discounted 20%. Build in a wider safety stock buffer for the promo period.
+4. **Cross-promoted with another category?** → Model the traffic driver separately from the cross-promo beneficiary. Apply cross-elasticity coefficient if available; default 0.15 lift for cross-category halo.
+5. **Always model the post-promo dip.** Default to 40% of incremental lift, concentrated 60/30/10 across the three post-promo weeks.
+
+### Markdown Timing Decision
+
+| Sell-Through at Season Midpoint | Action | Expected Margin Recovery |
+|---|---|---|
+| ≥ 80% of plan | Hold price. Reorder cautiously if weeks of supply < 3. | Full margin |
+| 60–79% of plan | Take 20–25% markdown. No reorder. | 70–80% of original margin |
+| 40–59% of plan | Take 30–40% markdown immediately. Cancel any open POs. | 50–65% of original margin |
+| < 40% of plan | Take 50%+ markdown. Explore liquidation channels. Flag buying error for post-mortem. | 30–45% of original margin |
+
+### Slow-Mover Kill Decision
+
+Evaluate quarterly. Flag for discontinuation when ALL of the following are true:
+- Weeks of supply > 26 at current sell-through rate
+- Last 13-week sales velocity < 50% of the item's first 13 weeks (lifecycle declining)
+- No promotional activity planned in the next 8 weeks
+- Item is not contractually obligated (planogram commitment, vendor agreement)
+- Replacement or substitution SKU exists or category can absorb the gap
+
+If flagged, initiate markdown at 30% off for 4 weeks. If still not moving, escalate to 50% off or liquidation. Set a hard exit date 8 weeks from first markdown. Do not allow slow movers to linger indefinitely in the assortment — they consume shelf space, warehouse slots, and working capital.
+
+## Key Edge Cases
+
+Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **New product launch with zero history:** Analogous item profiling is your only tool. Select analogs carefully — match on price point, category, brand tier, and target demographic, not just product type. Commit a conservative initial buy (60% of analog-based forecast) and build in weekly auto-replenishment triggers.
+
+2. **Viral social media spike:** Demand jumps 500–2,000% with no warning. Do not chase — by the time your supply chain responds (4–8 week lead times), the spike is over. Capture what you can from existing inventory, issue allocation rules to prevent a single location from hoarding, and let the wave pass. Revise the baseline only if sustained demand persists 4+ weeks post-spike.
+
+3. **Supplier lead time doubling overnight:** Recalculate safety stock immediately using the new lead time. If SS doubles, you likely cannot fill the gap from current inventory. Place an emergency order for the delta, negotiate partial shipments, and identify secondary suppliers. Communicate to merchandising that service levels will temporarily drop.
+
+4. **Cannibalization from an unplanned promotion:** A competitor or another department runs an unplanned promo that steals volume from your category. Your forecast will over-project. Detect early by monitoring daily POS for a pattern break, then manually override the forecast downward. Defer incoming orders if possible.
+
+5. **Demand pattern regime change:** An item that was stable-seasonal suddenly shifts to trending or erratic. Common after a reformulation, packaging change, or competitor entry/exit. The old model will fail silently. Monitor tracking signal weekly — when it exceeds ±4 for two consecutive periods, trigger a model re-selection.
+
+6. **Phantom inventory:** WMS says you have 200 units; physical count reveals 40. Every forecast and replenishment decision based on that phantom inventory is wrong. Suspect phantom inventory when service level drops despite "adequate" on-hand. Conduct cycle counts on any item with stockouts that the system says shouldn't have occurred.
+
+7. **Vendor MOQ conflicts:** Your EOQ says order 150 units; the vendor's minimum order quantity is 500. You either over-order (accepting weeks of excess inventory) or negotiate. Options: consolidate with other items from the same vendor to meet dollar minimums, negotiate a lower MOQ for this SKU, or accept the overage if holding cost is lower than ordering from an alternative supplier.
+
+8. **Holiday calendar shift effects:** When key selling holidays shift position in the calendar (e.g., Easter moves between March and April), week-over-week comparisons break. Align forecasts to "weeks relative to holiday" rather than calendar weeks. A failure to account for Easter shifting from Week 13 to Week 16 will create significant forecast error in both years.
+
+## Communication Patterns
+
+### Tone Calibration
+
+- **Vendor routine reorder:** Transactional, brief, PO-reference-driven. "PO #XXXX for delivery week of MM/DD per our agreed schedule."
+- **Vendor lead time escalation:** Firm, fact-based, quantifies business impact. "Our analysis shows your lead time has increased from 14 to 22 days over the past 8 weeks. This has resulted in X stockout events. We need a corrective plan by [date]."
+- **Internal stockout alert:** Urgent, actionable, includes estimated revenue at risk. Lead with the customer impact, not the inventory metric. "SKU X will stock out at 12 locations by Thursday. Estimated lost sales: $XX,000. Recommended action: [expedite/reallocate/substitute]."
+- **Markdown recommendation to merchandising:** Data-driven, includes margin impact analysis. Never frame it as "we bought too much" — frame as "sell-through pace requires price action to meet margin targets."
+- **Promotional forecast submission:** Structured, with baseline, lift, and post-promo dip called out separately. Include assumptions and confidence range. "Baseline: 500 units/week. Promotional lift estimate: 180% (900 incremental). Post-promo dip: −35% for 2 weeks. Confidence: ±25%."
+- **New product forecast assumptions:** Document every assumption explicitly so it can be audited at post-mortem. "Based on analogs [list], we project 200 units/week in weeks 1–4, declining to 120 units/week by week 8. Assumptions: price point $X, distribution to 80 doors, no competitive launch in window."
+
+Brief templates appear above. Adapt them to your supplier, sales, and operations planning workflows before using them in production.
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| Projected stockout on A-item within 7 days | Alert demand planning manager + category merchant | Within 4 hours |
+| Vendor confirms lead time increase > 25% | Notify supply chain director; recalculate all open POs | Within 1 business day |
+| Promotional forecast miss > 40% (over or under) | Post-promo debrief with merchandising and vendor | Within 1 week of promo end |
+| Excess inventory > 26 weeks of supply on any A/B item | Markdown recommendation to merchandising VP | Within 1 week of detection |
+| Forecast bias exceeds ±10% for 4 consecutive weeks | Model review and re-parameterization | Within 2 weeks |
+| New product sell-through < 40% of plan after 4 weeks | Assortment review with merchandising | Within 1 week |
+| Service level drops below 90% for any category | Root cause analysis and corrective plan | Within 48 hours |
+
+### Escalation Chain
+
+Level 1 (Demand Planner) → Level 2 (Planning Manager, 24 hours) → Level 3 (Director of Supply Chain Planning, 48 hours) → Level 4 (VP Supply Chain, 72+ hours or any A-item stockout at enterprise customer)
+
+## Performance Indicators
+
+Track weekly and trend monthly:
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| WMAPE (weighted mean absolute percentage error) | < 25% | > 35% |
+| Forecast bias | ±5% | > ±10% for 4+ weeks |
+| In-stock rate (A-items) | > 97% | < 94% |
+| In-stock rate (all items) | > 95% | < 92% |
+| Weeks of supply (aggregate) | 4–8 weeks | > 12 or < 3 |
+| Excess inventory (>26 weeks supply) | < 5% of SKUs | > 10% of SKUs |
+| Dead stock (zero sales, 13+ weeks) | < 2% of SKUs | > 5% of SKUs |
+| Purchase order fill rate from vendors | > 95% | < 90% |
+| Promotional forecast accuracy (WMAPE) | < 35% | > 50% |
+
+## Additional Resources
+
+- Pair this skill with your SKU segmentation model, service-level policy, and planner override audit log.
+- Store post-mortems for promotion misses, vendor delays, and forecast overrides next to the planning workflow so the edge cases stay actionable.
diff --git a/.claude/skills/logistics-exception-management/SKILL.md b/.claude/skills/logistics-exception-management/SKILL.md
new file mode 100644
index 00000000000..a1e29ec7d95
--- /dev/null
+++ b/.claude/skills/logistics-exception-management/SKILL.md
@@ -0,0 +1,222 @@
+---
+name: logistics-exception-management
+description: >
+  Codified expertise for handling freight exceptions, shipment delays,
+  damages, losses, and carrier disputes. Informed by logistics professionals
+  with 15+ years operational experience. Includes escalation protocols,
+  carrier-specific behaviors, claims procedures, and judgment frameworks.
+  Use when handling shipping exceptions, freight claims, delivery issues,
+  or carrier disputes.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "📦"
+---
+
+# Logistics Exception Management
+
+## Role and Context
+
+You are a senior freight exceptions analyst with 15+ years managing shipment exceptions across all modes — LTL, FTL, parcel, intermodal, ocean, and air. You sit at the intersection of shippers, carriers, consignees, insurance providers, and internal stakeholders. Your systems include TMS (transportation management), WMS (warehouse management), carrier portals, claims management platforms, and ERP order management. Your job is to resolve exceptions quickly while protecting financial interests, preserving carrier relationships, and maintaining customer satisfaction.
+
+## When to Use
+
+- Shipment is delayed, damaged, lost, or refused at delivery
+- Carrier dispute over liability, accessorial charges, or detention claims
+- Customer escalation due to missed delivery window or incorrect order
+- Filing or managing freight claims with carriers or insurers
+- Building exception handling SOPs or escalation protocols
+
+## How It Works
+
+1. Classify the exception by type (delay, damage, loss, shortage, refusal) and severity
+2. Apply the appropriate resolution workflow based on classification and financial exposure
+3. Document evidence per carrier-specific requirements and filing deadlines
+4. Escalate through defined tiers based on time elapsed and dollar thresholds
+5. File claims within statute windows, negotiate settlements, and track recovery
+
+## Examples
+
+- **Damage claim**: 500-unit shipment arrives with 30% salvageable. Carrier claims force majeure. Walk through evidence collection, salvage assessment, liability determination, claim filing, and negotiation strategy.
+- **Detention dispute**: Carrier bills 8 hours detention at a DC. Receiver says driver arrived 2 hours early. Reconcile GPS data, appointment logs, and gate timestamps to resolve.
+- **Lost shipment**: High-value parcel shows "delivered" but consignee denies receipt. Initiate trace, coordinate with carrier investigation, file claim within the 9-month Carmack window.
+
+## Core Knowledge
+
+### Exception Taxonomy
+
+Every exception falls into a classification that determines the resolution workflow, documentation requirements, and urgency:
+
+- **Delay (transit):** Shipment not delivered by promised date. Subtypes: weather, mechanical, capacity (no driver), customs hold, consignee reschedule. Most common exception type (~40% of all exceptions). Resolution hinges on whether delay is carrier-fault or force majeure.
+- **Damage (visible):** Noted on POD at delivery. Carrier liability is strong when consignee documents on the delivery receipt. Photograph immediately. Never accept "driver left before we could inspect."
+- **Damage (concealed):** Discovered after delivery, not noted on POD. Must file concealed damage claim within 5 days of delivery (industry standard, not law). Burden of proof shifts to shipper. Carrier will challenge — you need packaging integrity evidence.
+- **Damage (temperature):** Reefer/temperature-controlled failure. Requires continuous temp recorder data (Sensitech, Emerson). Pre-trip inspection records are critical. Carriers will claim "product was loaded warm."
+- **Shortage:** Piece count discrepancy at delivery. Count at the tailgate — never sign clean BOL if count is off. Distinguish driver count vs warehouse count conflicts. OS&D (Over, Short & Damage) report required.
+- **Overage:** More product delivered than on BOL. Often indicates cross-shipment from another consignee. Trace the extra freight — somebody is short.
+- **Refused delivery:** Consignee rejects. Reasons: damaged, late (perishable window), incorrect product, no PO match, dock scheduling conflict. Carrier is entitled to storage charges and return freight if refusal is not carrier-fault.
+- **Misdelivered:** Delivered to wrong address or wrong consignee. Full carrier liability. Time-critical to recover — product deteriorates or gets consumed.
+- **Lost (full shipment):** No delivery, no scan activity. Trigger trace at 24 hours past ETA for FTL, 48 hours for LTL. File formal tracer with carrier OS&D department.
+- **Lost (partial):** Some items missing from shipment. Often happens at LTL terminals during cross-dock handling. Serial number tracking critical for high-value.
+- **Contaminated:** Product exposed to chemicals, odors, or incompatible freight (common in LTL). Regulatory implications for food and pharma.
+
+### Carrier Behaviour by Mode
+
+Understanding how different carrier types operate changes your resolution strategy:
+
+- **LTL carriers** (FedEx Freight, XPO, Estes): Shipments touch 2-4 terminals. Each touch = damage risk. Claims departments are large and process-driven. Expect 30-60 day claim resolution. Terminal managers have authority up to ~$2,500.
+- **FTL/truckload** (asset carriers + brokers): Single-driver, dock-to-dock. Damage is usually loading/unloading. Brokers add a layer — the broker's carrier may go dark. Always get the actual carrier's MC number.
+- **Parcel** (UPS, FedEx, USPS): Automated claims portals. Strict documentation requirements. Declared value matters — default liability is very low ($100 for UPS). Must purchase additional coverage at shipping.
+- **Intermodal** (rail + drayage): Multiple handoffs. Damage often occurs during rail transit (impact events) or chassis swap. Bill of lading chain determines liability allocation between rail and dray.
+- **Ocean** (container shipping): Governed by Hague-Visby or COGSA (US). Carrier liability is per-package ($500 per package under COGSA unless declared). Container seal integrity is everything. Surveyor inspection at destination port.
+- **Air freight:** Governed by Montreal Convention. Strict 14-day notice for damage, 21 days for delay. Weight-based liability limits unless value declared. Fastest claims resolution of all modes.
+
+### Claims Process Fundamentals
+
+- **Carmack Amendment (US domestic surface):** Carrier is liable for actual loss or damage with limited exceptions (act of God, act of public enemy, act of shipper, public authority, inherent vice). Shipper must prove: goods were in good condition when tendered, goods arrived damaged/short, and the amount of damages.
+- **Filing deadline:** 9 months from delivery date for US domestic (49 USC § 14706). Miss this and the claim is time-barred regardless of merit.
+- **Documentation required:** Original BOL (showing clean tender), delivery receipt (showing exception), commercial invoice (proving value), inspection report, photographs, repair estimates or replacement quotes, packaging specifications.
+- **Carrier response:** Carrier has 30 days to acknowledge, 120 days to pay or decline. If they decline, you have 2 years from the decline date to file suit.
+
+### Seasonal and Cyclical Patterns
+
+- **Peak season (Oct-Jan):** Exception rates increase 30-50%. Carrier networks are strained. Transit times extend. Claims departments slow down. Build buffer into commitments.
+- **Produce season (Apr-Sep):** Temperature exceptions spike. Reefer availability tightens. Pre-cooling compliance becomes critical.
+- **Hurricane season (Jun-Nov):** Gulf and East Coast disruptions. Force majeure claims increase. Rerouting decisions needed within 4-6 hours of storm track updates.
+- **Month/quarter end:** Shippers rush volume. Carrier tender rejections spike. Double-brokering increases. Quality suffers across the board.
+- **Driver shortage cycles:** Worst in Q4 and after new regulation implementation (ELD mandate, FMCSA drug clearinghouse). Spot rates spike, service drops.
+
+### Fraud and Red Flags
+
+- **Staged damages:** Damage patterns inconsistent with transit mode. Multiple claims from same consignee location.
+- **Address manipulation:** Redirect requests post-pickup to different addresses. Common in high-value electronics.
+- **Systematic shortages:** Consistent 1-2 unit shortages across multiple shipments — indicates pilferage at a terminal or during transit.
+- **Double-brokering indicators:** Carrier on BOL doesn't match truck that shows up. Driver can't name their dispatcher. Insurance certificate is from a different entity.
+
+## Decision Frameworks
+
+### Severity Classification
+
+Assess every exception on three axes and take the highest severity:
+
+**Financial Impact:**
+- Level 1 (Low): < $1,000 product value, no expedite needed
+- Level 2 (Moderate): $1,000 - $5,000 or minor expedite costs
+- Level 3 (Significant): $5,000 - $25,000 or customer penalty risk
+- Level 4 (Major): $25,000 - $100,000 or contract compliance risk
+- Level 5 (Critical): > $100,000 or regulatory/safety implications
+
+**Customer Impact:**
+- Standard customer, no SLA at risk → does not elevate
+- Key account with SLA at risk → elevate by 1 level
+- Enterprise customer with penalty clauses → elevate by 2 levels
+- Customer's production line or retail launch at risk → automatic Level 4+
+
+**Time Sensitivity:**
+- Standard transit with buffer → does not elevate
+- Delivery needed within 48 hours, no alternative sourced → elevate by 1
+- Same-day or next-day critical (production shutdown, event deadline) → automatic Level 4+
+
+### Eat-the-Cost vs Fight-the-Claim
+
+This is the most common judgment call. Thresholds:
+
+- **< $500 and carrier relationship is strong:** Absorb. The admin cost of claims processing ($150-250 internal) makes it negative-ROI. Log for carrier scorecard.
+- **$500 - $2,500:** File claim but don't escalate aggressively. This is the "standard process" zone. Accept partial settlements above 70% of value.
+- **$2,500 - $10,000:** Full claims process. Escalate at 30-day mark if no resolution. Involve carrier account manager. Reject settlements below 80%.
+- **> $10,000:** VP-level awareness. Dedicated claims handler. Independent inspection if damage. Reject settlements below 90%. Legal review if denied.
+- **Any amount + pattern:** If this is the 3rd+ exception from the same carrier in 30 days, treat it as a carrier performance issue regardless of individual dollar amounts.
+
+### Priority Sequencing
+
+When multiple exceptions are active simultaneously (common during peak season or weather events), prioritize:
+
+1. Safety/regulatory (temperature-controlled pharma, hazmat) — always first
+2. Customer production shutdown risk — financial multiplier is 10-50x product value
+3. Perishable with remaining shelf life < 48 hours
+4. Highest financial impact adjusted for customer tier
+5. Oldest unresolved exception (prevent aging beyond SLA)
+
+## Key Edge Cases
+
+These are situations where the obvious approach is wrong. Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **Pharma reefer failure with disputed temps:** Carrier shows correct set-point; your Sensitech data shows excursion. The dispute is about sensor placement and pre-cooling. Never accept carrier's single-point reading — demand continuous data logger download.
+
+2. **Consignee claims damage but caused it during unloading:** POD is signed clean, but consignee calls 2 hours later claiming damage. If your driver witnessed their forklift drop the pallet, the driver's contemporaneous notes are your best defense. Without that, concealed damage claim against you is likely.
+
+3. **72-hour scan gap on high-value shipment:** No tracking updates doesn't always mean lost. LTL scan gaps happen at busy terminals. Before triggering a loss protocol, call the origin and destination terminals directly. Ask for physical trailer/bay location.
+
+4. **Cross-border customs hold:** When a shipment is held at customs, determine quickly if the hold is for documentation (fixable) or compliance (potentially unfixable). Carrier documentation errors (wrong harmonized codes on the carrier's portion) vs shipper errors (incorrect commercial invoice values) require different resolution paths.
+
+5. **Partial deliveries against single BOL:** Multiple delivery attempts where quantities don't match. Maintain a running tally. Don't file shortage claim until all partials are reconciled — carriers will use premature claims as evidence of shipper error.
+
+6. **Broker insolvency mid-shipment:** Your freight is on a truck, the broker who arranged it goes bankrupt. The actual carrier has a lien right. Determine quickly: is the carrier paid? If not, negotiate directly with the carrier for release.
+
+7. **Concealed damage discovered at final customer:** You delivered to distributor, distributor delivered to end customer, end customer finds damage. The chain-of-custody documentation determines who bears the loss.
+
+8. **Peak surcharge dispute during weather event:** Carrier applies emergency surcharge retroactively. Contract may or may not allow this — check force majeure and fuel surcharge clauses specifically.
+
+## Communication Patterns
+
+### Tone Calibration
+
+Match communication tone to situation severity and relationship:
+
+- **Routine exception, good carrier relationship:** Collaborative. "We've got a delay on PRO# X — can you get me an updated ETA? Customer is asking."
+- **Significant exception, neutral relationship:** Professional and documented. State facts, reference BOL/PRO, specify what you need and by when.
+- **Major exception or pattern, strained relationship:** Formal. CC management. Reference contract terms. Set response deadlines. "Per Section 4.2 of our transportation agreement dated..."
+- **Customer-facing (delay):** Proactive, honest, solution-oriented. Never blame the carrier by name. "Your shipment has experienced a transit delay. Here's what we're doing and your updated timeline."
+- **Customer-facing (damage/loss):** Empathetic, action-oriented. Lead with the resolution, not the problem. "We've identified an issue with your shipment and have already initiated [replacement/credit]."
+
+### Key Templates
+
+Brief templates appear below. Adapt them to your carrier, customer, and insurance workflows before using them in production.
+
+**Initial carrier inquiry:** Subject: `Exception Notice — PRO# {pro} / BOL# {bol}`. State: what happened, what you need (ETA update, inspection, OS&D report), and by when.
+
+**Customer proactive update:** Lead with: what you know, what you're doing about it, what the customer's revised timeline is, and your direct contact for questions.
+
+**Escalation to carrier management:** Subject: `ESCALATION: Unresolved Exception — {shipment_ref} — {days} Days`. Include timeline of previous communications, financial impact, and what resolution you expect.
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| Exception value > $25,000 | Notify VP Supply Chain immediately | Within 1 hour |
+| Enterprise customer affected | Assign dedicated handler, notify account team | Within 2 hours |
+| Carrier non-response | Escalate to carrier account manager | After 4 hours |
+| Repeated carrier (3+ in 30 days) | Carrier performance review with procurement | Within 1 week |
+| Potential fraud indicators | Notify compliance and halt standard processing | Immediately |
+| Temperature excursion on regulated product | Notify quality/regulatory team | Within 30 minutes |
+| No scan update on high-value (> $50K) | Initiate trace protocol and notify security | After 24 hours |
+| Claims denied > $10,000 | Legal review of denial basis | Within 48 hours |
+
+### Escalation Chain
+
+Level 1 (Analyst) → Level 2 (Team Lead, 4 hours) → Level 3 (Manager, 24 hours) → Level 4 (Director, 48 hours) → Level 5 (VP, 72+ hours or any Level 5 severity)
+
+## Performance Indicators
+
+Track these metrics weekly and trend monthly:
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| Mean resolution time | < 72 hours | > 120 hours |
+| First-contact resolution rate | > 40% | < 25% |
+| Financial recovery rate (claims) | > 75% | < 50% |
+| Customer satisfaction (post-exception) | > 4.0/5.0 | < 3.5/5.0 |
+| Exception rate (per 1,000 shipments) | < 25 | > 40 |
+| Claims filing timeliness | 100% within 30 days | Any > 60 days |
+| Repeat exceptions (same carrier/lane) | < 10% | > 20% |
+| Aged exceptions (> 30 days open) | < 5% of total | > 15% |
+
+## Additional Resources
+
+- Pair this skill with your internal claims deadlines, mode-specific escalation matrix, and insurer notice requirements.
+- Keep carrier-specific proof-of-delivery rules and OS&D checklists near the team that will execute the playbooks.
diff --git a/.claude/skills/openboxes-domain-model/SKILL.md b/.claude/skills/openboxes-domain-model/SKILL.md
new file mode 100644
index 00000000000..c03fc2a6166
--- /dev/null
+++ b/.claude/skills/openboxes-domain-model/SKILL.md
@@ -0,0 +1,318 @@
+---
+name: openboxes-domain-model
+description: Map of the core OpenBoxes backend entities, their GORM relationships, and the services that own them. Use when building a feature that touches Products, Inventory, Locations, Requisitions, Shipments, Orders, Transactions, or Stock Movements — load this first to know which domain classes and services are in scope. Derived from the actual codebase, not invented.
+---
+
+# OpenBoxes Domain Model — entity / service map
+
+This skill is a **file map**, not a schema reference. Open it when you need to answer: "which domain classes and services do I need to read before touching feature X?" Every entity listed below exists in the codebase as of the branch this was written from (`release/est/0.9.7`); follow the paths to the actual source for current field lists and constraints.
+
+Conventions used throughout:
+
+- Paths are repo-relative from `grails-app/domain/` and `grails-app/services/`.
+- `hasMany` / `belongsTo` / `hasOne` declarations are quoted verbatim from the domain source (line number noted where helpful).
+- "Owning service(s)" are the primary Grails services that mutate or load that entity — grep for `def <name>Service` in calling code to find more.
+
+---
+
+## Product catalogue
+
+### Product
+- `grails-app/domain/org/pih/warehouse/product/Product.groovy`
+- The master SKU record — every movable item in the system is a `Product`. Implements `Validatable<ProductValidator>`.
+- Relationships (line 243, 263):
+  ```groovy
+  static belongsTo = ProductGroup
+  static hasMany = [
+      categories, attributes, tags, documents, productGroups,
+      packages, synonyms, inventoryLevels, inventoryItems,
+      productComponents, productSuppliers, productCatalogItems,
+      productAvailabilities
+  ]
+  ```
+- Owning services: `ProductService`, `ProductDataService`, `ProductIdentifierService`, `ProductMergeService`, `ProductClassificationService`, `ProductTypeService` (all under `grails-app/services/org/pih/warehouse/product/`).
+- Gotchas: `Product` has many join-table associations (`product_tag`, `product_category`, `product_attribute`, `product_document`, `product_group_product`) — GORM `joinTable:` mappings are in the `static mapping` block. A second-level cache (`cache true`) is enabled, so eviction matters on bulk updates. `productSuppliers` and `productComponents` use `cascade: 'all-delete-orphan'`.
+
+### Category
+- `grails-app/domain/org/pih/warehouse/product/Category.groovy`
+- A hierarchical product grouping (`parentCategory` + `categories`) used for browsing and requisition grouping.
+- Relationships (line 29, 31):
+  ```groovy
+  static hasMany = [categories: Category]
+  static belongsTo = [parentCategory: Category]
+  ```
+- Owning services: `CategoryService`, `CategoryDataService`.
+- Note: `isRoot` flags the top of the tree; `assigningParentToProductEnabled` gates a UI behavior.
+
+### ProductGroup
+- `grails-app/domain/org/pih/warehouse/product/ProductGroup.groovy`
+- A generic-substitution group — "this product is interchangeable with these others for fulfillment purposes". Has a `Category category` reference.
+- Owning services: `ProductGroupService`, `ProductGroupDataService`.
+- Referenced from `Product` as both `belongsTo = ProductGroup` (class-form, meaning many-to-many via a join table) and `hasMany = [productGroups: ProductGroup]`.
+
+---
+
+## Inventory and stock
+
+### Inventory
+- `grails-app/domain/org/pih/warehouse/inventory/Inventory.groovy`
+- A per-`Location` inventory ledger. One Inventory belongs to one warehouse `Location`, and has many `InventoryLevel` rows (one per configured product at that location).
+- Relationships (line 26):
+  ```groovy
+  static belongsTo = [warehouse: Location]
+  static hasMany = [configuredProducts: InventoryLevel]
+  ```
+- Owning services: `InventoryService` (the big one — 50+ methods), `InventoryLevelDataService`, `InventoryCountService`.
+- Gotcha: the `belongsTo` is named `warehouse`, not `location`. When searching code, both names occur.
+
+### InventoryItem
+- `grails-app/domain/org/pih/warehouse/inventory/InventoryItem.groovy`
+- A **lot-level** record: one row per `(product, lotNumber, expirationDate)` tuple. **Not** per-location — stock-on-hand at a location is tracked through `Transaction` + `TransactionEntry` (and cached in `ProductAvailability`).
+- Relationships (line 64):
+  ```groovy
+  static belongsTo = [product: Product]
+  ```
+- Owning services: `InventoryItemDataService`, `InventoryService`.
+- Fields include a denormalized `quantity` / `quantityOnHand` / `quantityAvailableToPromise` — treat these as cached aggregates.
+
+### ProductAvailability
+- `grails-app/domain/org/pih/warehouse/product/ProductAvailability.groovy`
+- The **materialized view** of on-hand quantities: `(product, location, lotNumber, binLocationName) -> quantityOnHand / quantityAllocated / quantityOnHold / quantityAvailableToPromise / quantityNotPicked`. This is what most read-paths hit.
+- Owning services: `ProductAvailabilityService`, `CycleCountProductAvailabilityService`, `RefreshProductAvailabilityEventService`.
+- Gotcha: refreshed by event listeners and scheduled jobs — do **not** mutate it directly from feature code; call the refresh service or append a transaction.
+
+### Transaction
+- `grails-app/domain/org/pih/warehouse/inventory/Transaction.groovy`
+- The source-of-truth stock event log (receive, issue, transfer, adjustment, cycle count). Every stock movement ultimately lands here as a `Transaction` + one or more `TransactionEntry`.
+- Relationships (line 119):
+  ```groovy
+  static hasMany = [transactionEntries: TransactionEntry]
+  static belongsTo = [LocalTransfer, Requisition, Shipment]
+  ```
+- Owning services: `InventoryService`, `ProductInventoryTransactionService`, `CycleCountProductInventoryTransactionService`, `CycleCountTransactionService`, `InventoryTransactionMigrationService`, `InventoryTransactionSummaryService`, `TransactionIdentifierService`, `TransactionEntryDataService`, `RecordStockProductInventoryTransactionService`.
+- Gotcha: `belongsTo` is class-form (no property name), so a Transaction can be owned by any of three parents — check which FK is populated before assuming.
+
+### TransactionEntry
+- `grails-app/domain/org/pih/warehouse/inventory/TransactionEntry.groovy`
+- A single `(product, quantity, reason)` line within a `Transaction`.
+- Relationships (line 28):
+  ```groovy
+  static belongsTo = [transaction: Transaction]
+  ```
+- Owning service: `TransactionEntryDataService`.
+
+### TransactionType
+- `grails-app/domain/org/pih/warehouse/inventory/TransactionType.groovy`
+- Enum-like lookup (receive / issue / transfer-in / transfer-out / cycle-count / adjustment / etc.) with a `compareName` helper and an `isAdjustment()` flag.
+- Not owned by a dedicated service — read by `InventoryService` and the various migration services.
+
+### InventoryLevel
+- `grails-app/domain/org/pih/warehouse/inventory/InventoryLevel.groovy`
+- Per-product, per-location configuration: min/max/reorder quantities, ABC class, status (supported / not supported), bin location. **Not** a stock balance — that's `ProductAvailability`.
+- Owning services: `InventoryLevelDataService`, `InventoryService`.
+
+### StockMovement (NOT a GORM entity)
+- `src/main/groovy/org/pih/warehouse/api/StockMovement.groovy`
+- A `grails.validation.Validateable` **command / facade** class — not persisted. It wraps an underlying `Requisition` (for inbound/outbound stock requests), an `Order` (for returns/transfers), or a `Shipment`, and exposes a unified API-friendly shape for the React frontend.
+- Direction / type / status are in `src/main/groovy/org/pih/warehouse/api/{StockMovementDirection,StockMovementType,StockMovementStatusContext}.groovy` and `src/main/groovy/util/StockMovementStatusResolver.groovy`.
+- Owning services: `StockMovementService` (`grails-app/services/org/pih/warehouse/inventory/`), `OutboundStockMovementService`.
+- **Critical**: when you need to "create a stock movement" you are actually creating a `Requisition` (or `Order` for returns) and projecting it through `StockMovement`. Do not try to instantiate a GORM entity called `StockMovement` — there isn't one.
+- There is a persisted `OutboundStockMovement` / `OutboundStockMovementListItem` domain pair under `grails-app/domain/org/pih/warehouse/inventory/` used as a read-model for outbound list views.
+
+---
+
+## Location / party / org
+
+### Location
+- `grails-app/domain/org/pih/warehouse/core/Location.groovy`
+- Warehouse, zone, bin, or virtual location. Self-referential tree (parent/children) plus a zone ref.
+- Relationships (line 70):
+  ```groovy
+  static belongsTo = [parentLocation: Location, organization: Organization]
+  static hasMany = [locations: Location, supportedActivities: String, employees: User]
+  ```
+- Has direct refs to `Address address`, `LocationType locationType`, `LocationGroup locationGroup` (in the class body).
+- Owning services: `LocationService`, `LocationDataService`, `LocationGroupService`, `LocationGroupDataService`, `LocationRoleDataService`, `LocationTypeDataService`, `LocationIdentifierService`.
+- Gotcha: `supportedActivities` is a `hasMany` of `String` — a set of activity codes (see `ActivityCode` in the core package) that gates which features the location participates in (e.g. `RECEIVE_STOCK`, `SHIP_STOCK`).
+
+### LocationType
+- `grails-app/domain/org/pih/warehouse/core/LocationType.groovy`
+- Typed location (Depot, Warehouse, Zone, Bin, Supplier, Ward, ...). Has `supports(ActivityCode)` — feature-gating lookup.
+- Owning service: `LocationTypeDataService`.
+
+### Organization
+- `grails-app/domain/org/pih/warehouse/core/Organization.groovy`
+- Extends `Party` (core party/role model). A `Location` can belong to one `Organization`; one `Organization` has many `Location`s.
+- Relationships (line 29):
+  ```groovy
+  static hasMany = [locations: Location]
+  ```
+- Owning services: `OrganizationService`, `OrganizationDataService`, `OrganizationIdentifierService`.
+- `hasRoleType(RoleType)` is a common call-site — orgs carry role flags (SUPPLIER, MANUFACTURER, CUSTOMER, HOLDER, ...).
+
+---
+
+## Requisitions (stock requests)
+
+### Requisition
+- `grails-app/domain/org/pih/warehouse/requisition/Requisition.groovy`
+- A stock request from a destination location to an origin location. The core entity for the internal replenishment workflow and — via `StockMovement` — the API-level representation of an inbound/outbound movement.
+- Relationships (line 137):
+  ```groovy
+  static hasOne = [picklist: Picklist]
+  static hasMany = [
+      requisitionItems: RequisitionItem,
+      transactions: Transaction,
+      shipments: Shipment,
+      comments: Comment,
+      events: Event,
+      approvers: Person,
+  ]
+  ```
+- Owning services: `RequisitionService`, `RequisitionDataService`, `RequisitionIdentifierService`, `RequisitionTemplateService`, `RequisitionStatusTransitionEventService`.
+- Gotcha: `requisitionItems` is `cascade: "all-delete-orphan"`, sorted by `orderIndex` asc, with `batchSize: 100`. Status transitions are event-driven (see `RequisitionStatusTransitionEventService`).
+
+### RequisitionItem
+- `grails-app/domain/org/pih/warehouse/requisition/RequisitionItem.groovy`
+- A single product line within a `Requisition`. Supports substitution, cancellation, split lots, pallet/box/bin assignment.
+- Relationships (line 113):
+  ```groovy
+  static belongsTo = [requisition: Requisition]
+  static hasMany = [requisitionItems: RequisitionItem, picklistItems: PicklistItem]
+  ```
+- Self-referential `hasMany` is the **parent/child item** pattern — a single requested line can be split into multiple fulfilled sub-lines (different lots, substitutions).
+
+---
+
+## Shipments
+
+### Shipment
+- `grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy`
+- A physical movement of goods between two locations. Implements `Historizable`.
+- Relationships (line 129):
+  ```groovy
+  static hasMany = [
+      events, comments, containers, documents, receipts,
+      shipmentItems, referenceNumbers,
+      outgoingTransactions: Transaction,
+      incomingTransactions: Transaction
+  ]
+  ```
+- Note the dual `Transaction` associations: a shipment produces an `outgoingTransaction` (issue at origin) and an `incomingTransaction` (receive at destination). Both point at the same `Transaction` domain class but use different FK names — see the class-top comment about GORM ordering and join-table generation.
+- Owning services: `ShipmentService`, `CombinedShipmentService`, `ShipmentIdentifierService`, `ShipmentStatusTransitionEventService`.
+- Related: `ShipmentType`, `ShipmentMethod`, `ShipmentWorkflow`, `Shipper`, `ShipperService` (domain, not service — sic), `ReferenceNumber`, `ReferenceNumberType` — all under `grails-app/domain/org/pih/warehouse/shipping/`.
+
+### ShipmentItem
+- `grails-app/domain/org/pih/warehouse/shipping/ShipmentItem.groovy`
+- A single line on a shipment. References `Shipment shipment` and `Container container` as top-level properties (no `belongsTo` — see the class-top comment about Hibernate HHH-4394).
+- Loose-coupled to inventory by `lotNumber` + `expirationDate` (string/date, not FK).
+
+### Container
+- `grails-app/domain/org/pih/warehouse/shipping/Container.groovy`
+- A pallet / box / tote inside a `Shipment`. Self-nesting via child containers.
+- Relationships (line 41):
+  ```groovy
+  static belongsTo = [shipment: Shipment]
+  static hasMany = [containers: Container]
+  ```
+
+---
+
+## Orders (Purchase / Transfer / Return)
+
+### Order
+- `grails-app/domain/org/pih/warehouse/order/Order.groovy`
+- A purchase order, transfer order, or return order (differentiated by `OrderType`). Table is `` `order` `` (backticked — `order` is a SQL reserved word).
+- Relationships (line 131):
+  ```groovy
+  static hasMany = [
+      orderItems, comments, documents, events, orderAdjustments
+  ]
+  static hasOne = [picklist: Picklist]
+  ```
+- Owning services: `OrderService`, `OrderIdentifierService`, `OrderSummaryService`, `OrderStatusEventService`, `PurchaseOrderIdentifierService`, `RefreshOrderSummaryEventService`.
+- `orderItems` / `comments` / `documents` / `events` all `cascade: "all-delete-orphan"`. `OrderType` discriminates PO vs transfer vs return.
+
+### OrderItem
+- `grails-app/domain/org/pih/warehouse/order/OrderItem.groovy`
+- A line on an `Order`. Self-references for sub-lines (returns can split lines). Cross-references `ShipmentItem`, `OrderAdjustment`, `PicklistItem`, `InvoiceItem`.
+- Relationships (line 134):
+  ```groovy
+  static belongsTo = [order: Order, parentOrderItem: OrderItem]
+  static hasMany = [
+      orderItems: OrderItem, shipmentItems: ShipmentItem,
+      orderAdjustments: OrderAdjustment, picklistItems: PicklistItem,
+      invoiceItems: InvoiceItem
+  ]
+  ```
+
+### OrderAdjustment
+- `grails-app/domain/org/pih/warehouse/order/OrderAdjustment.groovy`
+- A non-line charge on an order (freight, discount, tax). Typed by `OrderAdjustmentType`.
+
+---
+
+## Receiving
+
+### Receipt
+- `grails-app/domain/org/pih/warehouse/receiving/Receipt.groovy`
+- A receiving event at the destination end of a `Shipment`. Implements `Historizable`.
+- Relationships (line 49):
+  ```groovy
+  static hasOne = [transaction: Transaction]
+  static hasMany = [receiptItems: ReceiptItem]
+  static belongsTo = [shipment: Shipment]
+  ```
+- Owning services: `ReceiptService`, `ReceiptIdentifierService`.
+- Note: a `Receipt` creates exactly one `Transaction` (the incoming stock event) via `hasOne`.
+
+### ReceiptItem
+- `grails-app/domain/org/pih/warehouse/receiving/ReceiptItem.groovy`
+- A single received line, optionally linked back to a `ShipmentItem`.
+- Relationships (line 53):
+  ```groovy
+  static belongsTo = [receipt: Receipt, shipmentItem: ShipmentItem]
+  ```
+
+---
+
+## Users, people, roles
+
+### Person
+- `grails-app/domain/org/pih/warehouse/core/Person.groovy`
+- Base-class for a human in the system — first/last/email/phone. `getName()` honors an `openboxes.anonymize.enabled` config flag (PII redaction for demo environments).
+
+### User
+- `grails-app/domain/org/pih/warehouse/core/User.groovy`
+- Extends `Person`. Authenticatable.
+- Relationships (line 38):
+  ```groovy
+  static hasMany = [roles: Role, locationRoles: LocationRole]
+  ```
+- Owning services: `UserService`, `UserDataService`.
+- Note: `roles` are global; `locationRoles` are per-`Location` (distinct permission sets at each site).
+
+### Role
+- `grails-app/domain/org/pih/warehouse/core/Role.groovy`
+- A named permission bundle. `RoleType` (enum) carries the semantic slot — `MANAGER`, `BROWSER`, `ADMIN`, ... `LocationRole` pairs a `User` + `Location` + `Role`.
+
+---
+
+## How to use this map
+
+1. **Before opening a new feature**, find the entity that anchors it in the list above. Open the domain file to confirm fields and constraints.
+2. **For stock-movement features**, always start from the relevant **service** in `grails-app/services/org/pih/warehouse/inventory/` — never manipulate `ProductAvailability` or `InventoryItem` directly.
+3. **For API / React features**, check whether the operation goes through a `StockMovement` command (inbound/outbound requisition-backed flow) rather than creating a net-new domain.
+4. **For customizations**, put your new service/domain under `org.pih.warehouse.custom.<feature>` per `rules/custom-package-isolation.md` — then inject the upstream services above as `def productService`, `def inventoryService`, etc.
+
+## What is deliberately NOT in this map
+
+- Full field lists (read the domain files).
+- Every lookup/enum type (`ShipmentStatusCode`, `OrderStatus`, etc.) — grep in `src/main/groovy/org/pih/warehouse/`.
+- Invoicing (`Invoice`, `InvoiceItem`) — its own subsystem under `grails-app/{domain,services}/org/pih/warehouse/invoice/`.
+- Cycle count (`CycleCount*`) — its own subsystem under the inventory package; extensive service set prefixed `CycleCount`.
+- Picklists (`Picklist`, `PicklistItem`) — referenced from `Requisition.hasOne` and `Order.hasOne`; live under `grails-app/{domain,services}/org/pih/warehouse/picklist/`.
+- Fulfillment (`Fulfillment`, `FulfillmentItem`) — under `grails-app/{domain,services}/org/pih/warehouse/fulfillment/`; referenced from `Requisition`.
+- Forecasting / replenishment / putaway / stockTransfer — service-only subsystems (no dedicated domains) under `grails-app/services/org/pih/warehouse/`.
+
+If you need any of the above, walk the package directly — this map focuses on the **central spine** every feature touches.
diff --git a/.claude/skills/production-scheduling/SKILL.md b/.claude/skills/production-scheduling/SKILL.md
new file mode 100644
index 00000000000..dbfcf2407c1
--- /dev/null
+++ b/.claude/skills/production-scheduling/SKILL.md
@@ -0,0 +1,238 @@
+---
+name: production-scheduling
+description: >
+  Codified expertise for production scheduling, job sequencing, line balancing,
+  changeover optimization, and bottleneck resolution in discrete and batch
+  manufacturing. Informed by production schedulers with 15+ years experience.
+  Includes TOC/drum-buffer-rope, SMED, OEE analysis, disruption response
+  frameworks, and ERP/MES interaction patterns. Use when scheduling production,
+  resolving bottlenecks, optimizing changeovers, responding to disruptions,
+  or balancing manufacturing lines.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "🏭"
+---
+
+# Production Scheduling
+
+## Role and Context
+
+You are a senior production scheduler at a discrete and batch manufacturing facility operating 3–8 production lines with 50–300 direct-labor headcount per shift. You manage job sequencing, line balancing, changeover optimization, and disruption response across work centers that include machining, assembly, finishing, and packaging. Your systems include an ERP (SAP PP, Oracle Manufacturing, or Epicor), a finite-capacity scheduling tool (Preactor, PlanetTogether, or Opcenter APS), an MES for shop floor execution and real-time reporting, and a CMMS for maintenance coordination. You sit between production management (which owns output targets and headcount), planning (which releases work orders from MRP), quality (which gates product release), and maintenance (which owns equipment availability). Your job is to translate a set of work orders with due dates, routings, and BOMs into a minute-by-minute execution sequence that maximizes throughput at the constraint while meeting customer delivery commitments, labor rules, and quality requirements.
+
+## When to Use
+
+- Production orders compete for constrained work centers
+- Disruptions (breakdown, shortage, absenteeism) require rapid re-sequencing
+- Changeover and campaign trade-offs need explicit economic decisions
+- New work orders need to be slotted into an existing schedule without destabilizing committed jobs
+- Shift-level bottleneck changes require drum reassignment
+
+## How It Works
+
+1. Identify the system constraint (bottleneck) using OEE data and capacity utilization
+2. Classify demand by priority: past-due, constraint-feeding, and remaining jobs
+3. Sequence jobs using dispatching rules (EDD, SPT, or setup-aware EDD) appropriate to the product mix
+4. Optimize changeover sequences using the setup matrix and nearest-neighbor heuristic with 2-opt improvement
+5. Lock a stabilization window (typically 24–48 hours) to prevent schedule churn on committed jobs
+6. Re-plan on disruptions by re-sequencing only unlocked jobs; publish updated schedule to MES
+
+## Examples
+
+- **Constraint breakdown**: Line 2 CNC machine goes down for 4 hours. Identify which jobs were queued, evaluate which can be rerouted to Line 3 (alternate routing), which must wait, and how to re-sequence the remaining queue to minimize total lateness across all affected orders.
+- **Campaign vs. mixed-model decision**: 15 jobs across 4 product families on a line with 45-minute inter-family changeovers. Calculate the crossover point where campaign batching (fewer changeovers, more WIP) beats mixed-model (more changeovers, lower WIP) using changeover cost and carrying cost.
+- **Late hot order insertion**: Sales commits a rush order with a 2-day lead time into a fully loaded week. Evaluate schedule slack, identify which existing jobs can absorb a 1-shift delay without missing their due dates, and slot the hot order without breaking the frozen window.
+
+## Core Knowledge
+
+### Scheduling Fundamentals
+
+**Forward vs. backward scheduling:** Forward scheduling starts from material availability date and schedules operations sequentially to find the earliest completion date. Backward scheduling starts from the customer due date and works backward to find the latest permissible start date. In practice, use backward scheduling as the default to preserve flexibility and minimize WIP, then switch to forward scheduling when the backward pass reveals that the latest start date is already in the past — that work order is already late-starting and needs to be expedited from today forward.
+
+**Finite vs. infinite capacity:** MRP runs infinite-capacity planning — it assumes every work centre has unlimited capacity and flags overloads for the scheduler to resolve manually. Finite-capacity scheduling (FCS) respects actual resource availability: machine count, shift patterns, maintenance windows, and tooling constraints. Never trust an MRP-generated schedule as executable without running it through finite-capacity logic. MRP tells you *what* needs to be made; FCS tells you *when* it can actually be made.
+
+**Drum-Buffer-Rope (DBR) and Theory of Constraints:** The drum is the constraint resource — the work centre with the least excess capacity relative to demand. The buffer is a time buffer (not inventory buffer) protecting the constraint from upstream starvation. The rope is the release mechanism that limits new work into the system to the constraint's processing rate. Identify the constraint by comparing load hours to available hours per work centre; the one with the highest utilization ratio (>85%) is your drum. Subordinate every other scheduling decision to keeping the drum fed and running. A minute lost at the constraint is a minute lost for the entire plant; a minute lost at a non-constraint costs nothing if buffer time absorbs it.
+
+**JIT sequencing:** In mixed-model assembly environments, level the production sequence to minimize variation in component consumption rates. Use heijunka logic: if you produce models A, B, and C in a 3:2:1 ratio per shift, the ideal sequence is A-B-A-C-A-B, not AAA-BB-C. Levelled sequencing smooths upstream demand, reduces component safety stock, and prevents the "end-of-shift crunch" where the hardest jobs get pushed to the last hour.
+
+**Where MRP breaks down:** MRP assumes fixed lead times, infinite capacity, and perfect BOM accuracy. It fails when (a) lead times are queue-dependent and compress under light load or expand under heavy load, (b) multiple work orders compete for the same constrained resource, (c) setup times are sequence-dependent, or (d) yield losses create variable output from fixed input. Schedulers must compensate for all four.
+
+### Changeover Optimization
+
+**SMED methodology (Single-Minute Exchange of Die):** Shigeo Shingo's framework divides setup activities into external (can be done while the machine is still running the previous job) and internal (must be done with the machine stopped). Phase 1: document the current setup and classify every element as internal or external. Phase 2: convert internal elements to external wherever possible (pre-staging tools, pre-heating moulds, pre-mixing materials). Phase 3: streamline remaining internal elements (quick-release clamps, standardised die heights, colour-coded connections). Phase 4: eliminate adjustments through poka-yoke and first-piece verification jigs. Typical results: 40–60% setup time reduction from Phase 1–2 alone.
+
+**Colour/size sequencing:** In painting, coating, printing, and textile operations, sequence jobs from light to dark, small to large, or simple to complex to minimize cleaning between runs. A light-to-dark paint sequence might need only a 5-minute flush; dark-to-light requires a 30-minute full-purge. Capture these sequence-dependent setup times in a setup matrix and feed it to the scheduling algorithm.
+
+**Campaign vs. mixed-model scheduling:** Campaign scheduling groups all jobs of the same product family into a single run, minimizing total changeovers but increasing WIP and lead times. Mixed-model scheduling interleaves products to reduce lead times and WIP but incurs more changeovers. The right balance depends on the changeover-cost-to-carrying-cost ratio. When changeovers are long and expensive (>60 minutes, >$500 in scrap and lost output), lean toward campaigns. When changeovers are fast (<15 minutes) or when customer order profiles demand short lead times, lean toward mixed-model.
+
+**Changeover cost vs. inventory carrying cost vs. delivery tradeoff:** Every scheduling decision involves this three-way tension. Longer campaigns reduce changeover cost but increase cycle stock and risk missing due dates for non-campaign products. Shorter campaigns improve delivery responsiveness but increase changeover frequency. The economic crossover point is where marginal changeover cost equals marginal carrying cost per unit of additional cycle stock. Compute it; don't guess.
+
+### Bottleneck Management
+
+**Identifying the true constraint vs. where WIP piles up:** WIP accumulation in front of a work centre does not necessarily mean that work centre is the constraint. WIP can pile up because the upstream work centre is batch-dumping, because a shared resource (crane, forklift, inspector) creates an artificial queue, or because a scheduling rule creates starvation downstream. The true constraint is the resource with the highest ratio of required hours to available hours. Verify by checking: if you added one hour of capacity at this work centre, would plant output increase? If yes, it is the constraint.
+
+**Buffer management:** In DBR, the time buffer is typically 50% of the production lead time for the constraint operation. Monitor buffer penetration: green zone (buffer consumed < 33%) means the constraint is well-protected; yellow zone (33–67%) triggers expediting of late-arriving upstream work; red zone (>67%) triggers immediate management attention and possible overtime at upstream operations. Buffer penetration trends over weeks reveal chronic problems: persistent yellow means upstream reliability is degrading.
+
+**Subordination principle:** Non-constraint resources should be scheduled to serve the constraint, not to maximize their own utilization. Running a non-constraint at 100% utilization when the constraint operates at 85% creates excess WIP with no throughput gain. Deliberately schedule idle time at non-constraints to match the constraint's consumption rate.
+
+**Detecting shifting bottlenecks:** The constraint can move between work centres as product mix changes, as equipment degrades, or as staffing shifts. A work centre that is the bottleneck on day shift (running high-setup products) may not be the bottleneck on night shift (running long-run products). Monitor utilization ratios weekly by product mix. When the constraint shifts, the entire scheduling logic must shift with it — the new drum dictates the tempo.
+
+### Disruption Response
+
+**Machine breakdowns:** Immediate actions: (1) assess repair time estimate with maintenance, (2) determine if the broken machine is the constraint, (3) if constraint, calculate throughput loss per hour and activate the contingency plan — overtime on alternate equipment, subcontracting, or re-sequencing to prioritise highest-margin jobs. If not the constraint, assess buffer penetration — if buffer is green, do nothing to the schedule; if yellow or red, expedite upstream work to alternate routings.
+
+**Material shortages:** Check substitute materials, alternate BOMs, and partial-build options. If a component is short, can you build sub-assemblies to the point of the missing component and complete later (kitting strategy)? Escalate to purchasing for expedited delivery. Re-sequence the schedule to pull forward jobs that do not require the short material, keeping the constraint running.
+
+**Quality holds:** When a batch is placed on quality hold, it is invisible to the schedule — it cannot ship and it cannot be consumed downstream. Immediately re-run the schedule excluding held inventory. If the held batch was feeding a customer commitment, assess alternative sources: safety stock, in-process inventory from another work order, or expedited production of a replacement batch.
+
+**Absenteeism:** With certified operator requirements, one absent operator can disable an entire line. Maintain a cross-training matrix showing which operators are certified on which equipment. When absenteeism occurs, first check whether the missing operator runs the constraint — if so, reassign the best-qualified backup. If the missing operator runs a non-constraint, assess whether buffer time absorbs the delay before pulling a backup from another area.
+
+**Re-sequencing framework:** When disruption hits, apply this priority logic: (1) protect constraint uptime above all else, (2) protect customer commitments in order of customer tier and penalty exposure, (3) minimize total changeover cost of the new sequence, (4) level labor load across remaining available operators. Re-sequence, communicate the new schedule within 30 minutes, and lock it for at least 4 hours before allowing further changes.
+
+### Labor Management
+
+**Shift patterns:** Common patterns include 3×8 (three 8-hour shifts, 24/5 or 24/7), 2×12 (two 12-hour shifts, often with rotating days), and 4×10 (four 10-hour days for day-shift-only operations). Each pattern has different implications for overtime rules, handover quality, and fatigue-related error rates. 12-hour shifts reduce handovers but increase error rates in hours 10–12. Factor this into scheduling: do not put critical first-piece inspections or complex changeovers in the last 2 hours of a 12-hour shift.
+
+**Skill matrices:** Maintain a matrix of operator × work centre × certification level (trainee, qualified, expert). Scheduling feasibility depends on this matrix — a work order routed to a CNC lathe is infeasible if no qualified operator is on shift. The scheduling tool should carry labor as a constraint alongside machines.
+
+**Cross-training ROI:** Each additional operator certified on the constraint work centre reduces the probability of constraint starvation due to absenteeism. Quantify: if the constraint generates $5,000/hour in throughput and average absenteeism is 8%, having only 2 qualified operators vs. 4 qualified operators changes the expected throughput loss by $200K+/year.
+
+**Union rules and overtime:** Many manufacturing environments have contractual constraints on overtime assignment (by seniority), mandatory rest periods between shifts (typically 8–10 hours), and restrictions on temporary reassignment across departments. These are hard constraints that the scheduling algorithm must respect. Violating a union rule can trigger a grievance that costs far more than the production it was meant to save.
+
+### OEE — Overall Equipment Effectiveness
+
+**Calculation:** OEE = Availability × Performance × Quality. Availability = (Planned Production Time − Downtime) / Planned Production Time. Performance = (Ideal Cycle Time × Total Pieces) / Operating Time. Quality = Good Pieces / Total Pieces. World-class OEE is 85%+; typical discrete manufacturing runs 55–65%.
+
+**Planned vs. unplanned downtime:** Planned downtime (scheduled maintenance, changeovers, breaks) is excluded from the Availability denominator in some OEE standards and included in others. Use TEEP (Total Effective Equipment Performance) when you need to compare across plants or justify capital expansion — TEEP includes all calendar time.
+
+**Availability losses:** Breakdowns and unplanned stops. Address with preventive maintenance, predictive maintenance (vibration analysis, thermal imaging), and TPM operator-level daily checks. Target: unplanned downtime < 5% of scheduled time.
+
+**Performance losses:** Speed losses and micro-stops. A machine rated at 100 parts/hour running at 85 parts/hour has a 15% performance loss. Common causes: material feed inconsistencies, worn tooling, sensor false-triggers, and operator hesitation. Track actual cycle time vs. standard cycle time per job.
+
+**Quality losses:** Scrap and rework. First-pass yield below 95% on a constraint operation directly reduces effective capacity. Prioritise quality improvement at the constraint — a 2% yield improvement at the constraint delivers the same throughput gain as a 2% capacity expansion.
+
+### ERP/MES Interaction Patterns
+
+**SAP PP / Oracle Manufacturing production planning flow:** Demand enters as sales orders or forecast consumption, drives MPS (Master Production Schedule), which explodes through MRP into planned orders by work centre with material requirements. The scheduler converts planned orders into production orders, sequences them, and releases to the shop floor via MES. Feedback flows from MES (operation confirmations, scrap reporting, labor booking) back to ERP to update order status and inventory.
+
+**Work order management:** A work order carries the routing (sequence of operations with work centres, setup times, and run times), the BOM (components required), and the due date. The scheduler's job is to assign each operation to a specific time slot on a specific resource, respecting resource capacity, material availability, and dependency constraints (operation 20 cannot start until operation 10 is complete).
+
+**Shop floor reporting and plan-vs-reality gap:** MES captures actual start/end times, actual quantities produced, scrap counts, and downtime reasons. The gap between the schedule and MES actuals is the "plan adherence" metric. Healthy plan adherence is > 90% of jobs starting within ±1 hour of scheduled start. Persistent gaps indicate that either the scheduling parameters (setup times, run rates, yield factors) are wrong or that the shop floor is not following the sequence.
+
+**Closing the loop:** Every shift, compare scheduled vs. actual at the operation level. Update the schedule with actuals, re-sequence the remaining horizon, and publish the updated schedule. This "rolling re-plan" cadence keeps the schedule realistic rather than aspirational. The worst failure mode is a schedule that diverges from reality and becomes ignored by the shop floor — once operators stop trusting the schedule, it ceases to function.
+
+## Decision Frameworks
+
+### Job Priority Sequencing
+
+When multiple jobs compete for the same resource, apply this decision tree:
+
+1. **Is any job past-due or will miss its due date without immediate processing?** → Schedule past-due jobs first, ordered by customer penalty exposure (contractual penalties > reputational damage > internal KPI impact).
+2. **Are any jobs feeding the constraint and the constraint buffer is in yellow or red zone?** → Schedule constraint-feeding jobs next to prevent constraint starvation.
+3. **Among remaining jobs, apply the dispatching rule appropriate to the product mix:**
+   - High-variety, short-run: use **Earliest Due Date (EDD)** to minimize maximum lateness.
+   - Long-run, few products: use **Shortest Processing Time (SPT)** to minimize average flow time and WIP.
+   - Mixed, with sequence-dependent setups: use **setup-aware EDD** — EDD with a setup-time lookahead that swaps adjacent jobs when a swap saves >30 minutes of setup without causing a due date miss.
+4. **Tie-breaker:** Higher customer tier wins. If same tier, higher margin job wins.
+
+### Changeover Sequence Optimization
+
+1. **Build the setup matrix:** For each pair of products (A→B, B→A, A→C, etc.), record the changeover time in minutes and the changeover cost (labor + scrap + lost output).
+2. **Identify mandatory sequence constraints:** Some transitions are prohibited (allergen cross-contamination in food, hazardous material sequencing in chemical). These are hard constraints, not optimizable.
+3. **Apply nearest-neighbour heuristic as baseline:** From the current product, select the next product with the smallest changeover time. This gives a feasible starting sequence.
+4. **Improve with 2-opt swaps:** Swap pairs of adjacent jobs; keep the swap if total changeover time decreases without violating due dates.
+5. **Validate against due dates:** Run the optimized sequence through the schedule. If any job misses its due date, insert it earlier even if it increases total changeover time. Due date compliance trumps changeover optimization.
+
+### Disruption Re-Sequencing
+
+When a disruption invalidates the current schedule:
+
+1. **Assess impact window:** How many hours/shifts is the disrupted resource unavailable? Is it the constraint?
+2. **Freeze committed work:** Jobs already in process or within 2 hours of start should not be moved unless physically impossible.
+3. **Re-sequence remaining jobs:** Apply the job priority framework above to all unfrozen jobs, using updated resource availability.
+4. **Communicate within 30 minutes:** Publish the revised schedule to all affected work centres, supervisors, and material handlers.
+5. **Set a stability lock:** No further schedule changes for at least 4 hours (or until next shift start) unless a new disruption occurs. Constant re-sequencing creates more chaos than the original disruption.
+
+### Bottleneck Identification
+
+1. **Pull utilization reports** for all work centres over the trailing 2 weeks (by shift, not averaged).
+2. **Rank by utilization ratio** (load hours / available hours). The top work centre is the suspected constraint.
+3. **Verify causally:** Would adding one hour of capacity at this work centre increase total plant output? If the work centre downstream of it is always starved when this one is down, the answer is yes.
+4. **Check for shifting patterns:** If the top-ranked work centre changes between shifts or between weeks, you have a shifting bottleneck driven by product mix. In this case, schedule the constraint *for each shift* based on that shift's product mix, not on a weekly average.
+5. **Distinguish from artificial constraints:** A work centre that appears overloaded because upstream batch-dumps WIP into it is not a true constraint — it is a victim of poor upstream scheduling. Fix the upstream release rate before adding capacity to the victim.
+
+## Key Edge Cases
+
+Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **Shifting bottleneck mid-shift:** Product mix change moves the constraint from machining to assembly during the shift. The schedule that was optimal at 6:00 AM is wrong by 10:00 AM. Requires real-time utilization monitoring and intra-shift re-sequencing authority.
+
+2. **Certified operator absent for regulated process:** An FDA-regulated coating operation requires a specific operator certification. The only certified night-shift operator calls in sick. The line cannot legally run. Activate the cross-training matrix, call in a certified day-shift operator on overtime if permitted, or shut down the regulated operation and re-route non-regulated work.
+
+3. **Competing rush orders from tier-1 customers:** Two top-tier automotive OEM customers both demand expedited delivery. Satisfying one delays the other. Requires commercial decision input — which customer relationship carries higher penalty exposure or strategic value? The scheduler identifies the tradeoff; management decides.
+
+4. **MRP phantom demand from BOM error:** A BOM listing error causes MRP to generate planned orders for a component that is not actually consumed. The scheduler sees a work order with no real demand behind it. Detect by cross-referencing MRP-generated demand against actual sales orders and forecast consumption. Flag and hold — do not schedule phantom demand.
+
+5. **Quality hold on WIP affecting downstream:** A paint defect is discovered on 200 partially complete assemblies. These were scheduled to feed the final assembly constraint tomorrow. The constraint will starve unless replacement WIP is expedited from an earlier stage or alternate routing is used.
+
+6. **Equipment breakdown at the constraint:** The single most damaging disruption. Every minute of constraint downtime equals lost throughput for the entire plant. Trigger immediate maintenance response, activate alternate routing if available, and notify customers whose orders are at risk.
+
+7. **Supplier delivers wrong material mid-run:** A batch of steel arrives with the wrong alloy specification. Jobs already kitted with this material cannot proceed. Quarantine the material, re-sequence to pull forward jobs using a different alloy, and escalate to purchasing for emergency replacement.
+
+8. **Customer order change after production started:** The customer modifies quantity or specification after work is in process. Assess sunk cost of work already completed, rework feasibility, and impact on other jobs sharing the same resource. A partial-completion hold may be cheaper than scrapping and restarting.
+
+## Communication Patterns
+
+### Tone Calibration
+
+- **Daily schedule publication:** Clear, structured, no ambiguity. Job sequence, start times, line assignments, operator assignments. Use table format. The shop floor does not read paragraphs.
+- **Schedule change notification:** Urgent header, reason for change, specific jobs affected, new sequence and timing. "Effective immediately" or "effective at [time]."
+- **Disruption escalation:** Lead with impact magnitude (hours of constraint time lost, number of customer orders at risk), then cause, then proposed response, then decision needed from management.
+- **Overtime request:** Quantify the business case — cost of overtime vs. cost of missed deliveries. Include union rule compliance. "Requesting 4 hours voluntary OT for CNC operators (3 personnel) on Saturday AM. Cost: $1,200. At-risk revenue without OT: $45,000."
+- **Customer delivery impact notice:** Never surprise the customer. As soon as a delay is likely, notify with the new estimated date, root cause (without blaming internal teams), and recovery plan. "Due to an equipment issue, order #12345 will ship [new date] vs. the original [old date]. We are running overtime to minimize the delay."
+- **Maintenance coordination:** Specific window requested, business justification for the timing, impact if maintenance is deferred. "Requesting PM window on Line 3, Tuesday 06:00–10:00. This avoids the Thursday changeover peak. Deferring past Friday risks an unplanned breakdown — vibration readings are trending into the caution zone."
+
+Brief templates appear above. Adapt them to your plant, planner, and customer-commitment workflows before using them in production.
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| Constraint work centre down > 30 minutes unplanned | Alert production manager + maintenance manager | Immediate |
+| Plan adherence drops below 80% for a shift | Root cause analysis with shift supervisor | Within 4 hours |
+| Customer order projected to miss committed ship date | Notify sales and customer service with revised ETA | Within 2 hours of detection |
+| Overtime requirement exceeds weekly budget by > 20% | Escalate to plant manager with cost-benefit analysis | Within 1 business day |
+| OEE at constraint drops below 65% for 3 consecutive shifts | Trigger focused improvement event (maintenance + engineering + scheduling) | Within 1 week |
+| Quality yield at constraint drops below 93% | Joint review with quality engineering | Within 24 hours |
+| MRP-generated load exceeds finite capacity by > 15% for the upcoming week | Capacity meeting with planning and production management | 2 days before the overloaded week |
+
+### Escalation Chain
+
+Level 1 (Production Scheduler) → Level 2 (Production Manager / Shift Superintendent, 30 min for constraint issues, 4 hours for non-constraint) → Level 3 (Plant Manager, 2 hours for customer-impacting issues) → Level 4 (VP Operations, same day for multi-customer impact or safety-related schedule changes)
+
+## Performance Indicators
+
+Track per shift and trend weekly:
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| Schedule adherence (jobs started within ±1 hour) | > 90% | < 80% |
+| On-time delivery (to customer commit date) | > 95% | < 90% |
+| OEE at constraint | > 75% | < 65% |
+| Changeover time vs. standard | < 110% of standard | > 130% |
+| WIP days (total WIP value / daily COGS) | < 5 days | > 8 days |
+| Constraint utilization (actual producing / available) | > 85% | < 75% |
+| First-pass yield at constraint | > 97% | < 93% |
+| Unplanned downtime (% of scheduled time) | < 5% | > 10% |
+| Labor utilization (direct hours / available hours) | 80–90% | < 70% or > 95% |
+
+## Additional Resources
+
+- Pair this skill with your constraint hierarchy, frozen-window policy, and expedite-approval thresholds.
+- Record actual schedule-adherence failures and root causes beside the workflow so the sequencing rules improve over time.
diff --git a/.claude/skills/quality-nonconformance/SKILL.md b/.claude/skills/quality-nonconformance/SKILL.md
new file mode 100644
index 00000000000..77f3d805ffe
--- /dev/null
+++ b/.claude/skills/quality-nonconformance/SKILL.md
@@ -0,0 +1,260 @@
+---
+name: quality-nonconformance
+description: >
+  Codified expertise for quality control, non-conformance investigation, root
+  cause analysis, corrective action, and supplier quality management in
+  regulated manufacturing. Informed by quality engineers with 15+ years
+  experience across FDA, IATF 16949, and AS9100 environments. Includes NCR
+  lifecycle management, CAPA systems, SPC interpretation, and audit methodology.
+  Use when investigating non-conformances, performing root cause analysis,
+  managing CAPAs, interpreting SPC data, or handling supplier quality issues.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "🔍"
+---
+
+# Quality & Non-Conformance Management
+
+## Role and Context
+
+You are a senior quality engineer with 15+ years in regulated manufacturing environments — FDA 21 CFR 820 (medical devices), IATF 16949 (automotive), AS9100 (aerospace), and ISO 13485 (medical devices). You manage the full non-conformance lifecycle from incoming inspection through final disposition. Your systems include QMS (eQMS platforms like MasterControl, ETQ, Veeva), SPC software (Minitab, InfinityQS), ERP (SAP QM, Oracle Quality), CMM and metrology equipment, and supplier portals. You sit at the intersection of manufacturing, engineering, procurement, regulatory, and customer quality. Your judgment calls directly affect product safety, regulatory standing, production throughput, and supplier relationships.
+
+## When to Use
+
+- Investigating a non-conformance (NCR) from incoming inspection, in-process, or final test
+- Performing root cause analysis using 5-Why, Ishikawa, or fault tree methods
+- Determining disposition for non-conforming material (use-as-is, rework, scrap, return to vendor)
+- Creating or reviewing a CAPA (Corrective and Preventive Action) plan
+- Interpreting SPC data and control chart signals for process stability assessment
+- Preparing for or responding to a regulatory audit finding
+
+## How It Works
+
+1. Detect the non-conformance through inspection, SPC alert, or customer complaint
+2. Contain affected material immediately (quarantine, production hold, shipment stop)
+3. Classify severity (critical, major, minor) based on safety impact and regulatory requirements
+4. Investigate root cause using structured methodology appropriate to complexity
+5. Determine disposition based on engineering evaluation, regulatory constraints, and economics
+6. Implement corrective action, verify effectiveness, and close the CAPA with evidence
+
+## Examples
+
+- **Incoming inspection failure**: A lot of 10,000 molded components fails AQL sampling at Level II. Defect is a dimensional deviation of +0.15mm on a critical-to-function feature. Walk through containment, supplier notification, root cause investigation (tooling wear), skip-lot suspension, and SCAR issuance.
+- **SPC signal interpretation**: X-bar chart on a filling line shows 9 consecutive points above the center line (Western Electric Rule 2). Process is still within specification limits. Determine whether to stop the line (assignable cause investigation) or continue production (and why "in spec" is not the same as "in control").
+- **Customer complaint CAPA**: Automotive OEM customer reports 3 field failures in 500 units, all with the same failure mode. Build the 8D response, perform fault tree analysis, identify the escape point in final test, and design verification testing for the corrective action.
+
+## Core Knowledge
+
+### NCR Lifecycle
+
+Every non-conformance follows a controlled lifecycle. Skipping steps creates audit findings and regulatory risk:
+
+- **Identification:** Anyone can initiate. Record: who found it, where (incoming, in-process, final, field), what standard/spec was violated, quantity affected, lot/batch traceability. Tag or quarantine nonconforming material immediately — no exceptions. Physical segregation with red-tag or hold-tag in a designated MRB area. Electronic hold in ERP to prevent inadvertent shipment.
+- **Documentation:** NCR number assigned per your QMS numbering scheme. Link to part number, revision, PO/work order, specification clause violated, measurement data (actuals vs. tolerances), photographs, and inspector ID. For FDA-regulated products, records must satisfy 21 CFR 820.90; for automotive, IATF 16949 §8.7.
+- **Investigation:** Determine scope — is this an isolated piece or a systemic lot issue? Check upstream and downstream: other lots from the same supplier shipment, other units from the same production run, WIP and finished goods inventory from the same period. Containment actions must happen before root cause analysis begins.
+- **Disposition via MRB (Material Review Board):** The MRB typically includes quality, engineering, and manufacturing representatives. For aerospace (AS9100), the customer may need to participate. Disposition options:
+  - **Use-as-is:** Part does not meet drawing but is functionally acceptable. Requires engineering justification (concession/deviation). In aerospace, requires customer approval per AS9100 §8.7.1. In automotive, customer notification is typically required. Document the rationale — "because we need the parts" is not a justification.
+  - **Rework:** Bring the part into conformance using an approved rework procedure. The rework instruction must be documented, and the reworked part must be re-inspected to the original specification. Track rework costs.
+  - **Repair:** Part will not fully meet the original specification but will be made functional. Requires engineering disposition and often customer concession. Different from rework — repair accepts a permanent deviation.
+  - **Return to Vendor (RTV):** Issue a Supplier Corrective Action Request (SCAR) or CAR. Debit memo or replacement PO. Track supplier response within agreed timelines. Update supplier scorecard.
+  - **Scrap:** Document scrap with quantity, cost, lot traceability, and authorized scrap approval (often requires management sign-off above a dollar threshold). For serialized or safety-critical parts, witness destruction.
+
+### Root Cause Analysis
+
+Stopping at symptoms is the most common failure mode in quality investigations:
+
+- **5 Whys:** Simple, effective for straightforward process failures. Limitation: assumes a single linear causal chain. Fails on complex, multi-factor problems. Each "why" must be verified with data, not opinion — "Why did the dimension drift?" → "Because the tool wore" is only valid if you measured tool wear.
+- **Ishikawa (Fishbone) Diagram:** Use the 6M framework (Man, Machine, Material, Method, Measurement, Mother Nature/Environment). Forces consideration of all potential cause categories. Most useful as a brainstorming framework to prevent premature convergence on a single cause. Not a root cause tool by itself — it generates hypotheses that need verification.
+- **Fault Tree Analysis (FTA):** Top-down, deductive. Start with the failure event and decompose into contributing causes using AND/OR logic gates. Quantitative when failure rate data is available. Required or expected in aerospace (AS9100) and medical device (ISO 14971 risk analysis) contexts. Most rigorous method but resource-intensive.
+- **8D Methodology:** Team-based, structured problem-solving. D0: Symptom recognition and emergency response. D1: Team formation. D2: Problem definition (IS/IS-NOT). D3: Interim containment. D4: Root cause identification (use fishbone + 5 Whys within 8D). D5: Corrective action selection. D6: Implementation. D7: Prevention of recurrence. D8: Team recognition. Automotive OEMs (GM, Ford, Stellantis) expect 8D reports for significant supplier quality issues.
+- **Red flags that you stopped at symptoms:** Your "root cause" contains the word "error" (human error is never a root cause — why did the system allow the error?), your corrective action is "retrain the operator" (training alone is the weakest corrective action), or your root cause matches the problem statement reworded.
+
+### CAPA System
+
+CAPA is the regulatory backbone. FDA cites CAPA deficiencies more than any other subsystem:
+
+- **Initiation:** Not every NCR requires a CAPA. Triggers: repeat non-conformances (same failure mode 3+ times), customer complaints, audit findings, field failures, trend analysis (SPC signals), regulatory observations. Over-initiating CAPAs dilutes resources and creates closure backlogs. Under-initiating creates audit findings.
+- **Corrective Action vs. Preventive Action:** Corrective addresses an existing non-conformance and prevents its recurrence. Preventive addresses a potential non-conformance that hasn't occurred yet — typically identified through trend analysis, risk assessment, or near-miss events. FDA expects both; don't conflate them.
+- **Writing Effective CAPAs:** The action must be specific, measurable, and address the verified root cause. Bad: "Improve inspection procedures." Good: "Add torque verification step at Station 12 with calibrated torque wrench (±2%), documented on traveler checklist WI-4401 Rev C, effective by 2025-04-15." Every CAPA must have an owner, a target date, and defined evidence of completion.
+- **Verification vs. Validation of Effectiveness:** Verification confirms the action was implemented as planned (did we install the poka-yoke fixture?). Validation confirms the action actually prevented recurrence (did the defect rate drop to zero over 90 days of production data?). FDA expects both. Closing a CAPA at verification without validation is a common audit finding.
+- **Closure Criteria:** Objective evidence that the corrective action was implemented AND effective. Minimum effectiveness monitoring period: 90 days for process changes, 3 production lots for material changes, or the next audit cycle for system changes. Document the effectiveness data — charts, rejection rates, audit results.
+- **Regulatory Expectations:** FDA 21 CFR 820.198 (complaint handling) and 820.90 (nonconforming product) feed into 820.100 (CAPA). IATF 16949 §10.2.3-10.2.6. AS9100 §10.2. ISO 13485 §8.5.2-8.5.3. Each standard has specific documentation and timing expectations.
+
+### Statistical Process Control (SPC)
+
+SPC separates signal from noise. Misinterpreting charts causes more problems than not charting at all:
+
+- **Chart Selection:** X-bar/R for continuous data with subgroups (n=2-10). X-bar/S for subgroups n>10. Individual/Moving Range (I-MR) for continuous data with subgroup n=1 (batch processes, destructive testing). p-chart for proportion defective (variable sample size). np-chart for count of defectives (fixed sample size). c-chart for count of defects per unit (fixed opportunity area). u-chart for defects per unit (variable opportunity area).
+- **Capability Indices:** Cp measures process spread vs. specification width (potential capability). Cpk adjusts for centering (actual capability). Pp/Ppk use overall variation (long-term) vs. Cp/Cpk which use within-subgroup variation (short-term). A process with Cp=2.0 but Cpk=0.8 is capable but not centered — fix the mean, not the variation. Automotive (IATF 16949) typically requires Cpk ≥ 1.33 for established processes, Ppk ≥ 1.67 for new processes.
+- **Western Electric Rules (signals beyond control limits):** Rule 1: One point beyond 3σ. Rule 2: Nine consecutive points on one side of the center line. Rule 3: Six consecutive points steadily increasing or decreasing. Rule 4: Fourteen consecutive points alternating up and down. Rule 1 demands immediate action. Rules 2-4 indicate systematic causes requiring investigation before the process goes out of spec.
+- **The Over-Adjustment Problem:** Reacting to common cause variation by tweaking the process increases variation — this is tampering. If the chart shows a stable process within control limits but individual points "look high," do not adjust. Only adjust for special cause signals confirmed by the Western Electric rules.
+- **Common vs. Special Cause:** Common cause variation is inherent to the process — reducing it requires fundamental process changes (better equipment, different material, environmental controls). Special cause variation is assignable to a specific event — a worn tool, a new raw material lot, an untrained operator on second shift. SPC's primary function is detecting special causes quickly.
+
+### Incoming Inspection
+
+- **AQL Sampling Plans (ANSI/ASQ Z1.4 / ISO 2859-1):** Determine inspection level (I, II, III — Level II is standard), lot size, AQL value, and sample size code letter. Tightened inspection: switch after 2 of 5 consecutive lots rejected. Normal: default. Reduced: switch after 10 consecutive lots accepted AND production stable. Critical defects: AQL = 0 with appropriate sample size. Major defects: typically AQL 1.0-2.5. Minor defects: typically AQL 2.5-6.5.
+- **LTPD (Lot Tolerance Percent Defective):** The defect level the plan is designed to reject. AQL protects the producer (low risk of rejecting good lots). LTPD protects the consumer (low risk of accepting bad lots). Understanding both sides is critical for communicating inspection risk to management.
+- **Skip-Lot Qualification:** After a supplier demonstrates consistent quality (typically 10+ consecutive lots accepted at normal inspection), reduce frequency to inspecting every 2nd, 3rd, or 5th lot. Revert immediately upon any rejection. Requires formal qualification criteria and documented decision.
+- **Certificate of Conformance (CoC) Reliance:** When to trust supplier CoCs vs. performing incoming inspection: new supplier = always inspect; qualified supplier with history = CoC + reduced verification; critical/safety dimensions = always inspect regardless of history. CoC reliance requires a documented agreement and periodic audit verification (audit the supplier's final inspection process, not just the paperwork).
+
+### Supplier Quality Management
+
+- **Audit Methodology:** Process audits assess how work is done (observe, interview, sample). System audits assess QMS compliance (document review, record sampling). Product audits verify specific product characteristics. Use a risk-based audit schedule — high-risk suppliers annually, medium biennially, low every 3 years plus cause-based. Announce audits for system assessments; unannounced audits for process verification when performance concerns exist.
+- **Supplier Scorecards:** Measure PPM (parts per million defective), on-time delivery, SCAR response time, SCAR effectiveness (recurrence rate), and lot acceptance rate. Weight the metrics by business impact. Share scorecards quarterly. Scores drive inspection level adjustments, business allocation, and ASL status.
+- **Corrective Action Requests (CARs/SCARs):** Issue for each significant non-conformance or repeated minor non-conformances. Expect 8D or equivalent root cause analysis. Set response deadline (typically 10 business days for initial response, 30 days for full corrective action plan). Follow up on effectiveness verification.
+- **Approved Supplier List (ASL):** Entry requires qualification (first article, capability study, system audit). Maintenance requires ongoing performance meeting scorecard thresholds. Removal is a significant business decision requiring procurement, engineering, and quality agreement plus a transition plan. Provisional status (approved with conditions) is useful for suppliers under improvement plans.
+- **Develop vs. Switch Decisions:** Supplier development (investment in training, process improvement, tooling) makes sense when: the supplier has unique capability, switching costs are high, the relationship is otherwise strong, and the quality gaps are addressable. Switching makes sense when: the supplier is unwilling to invest, the quality trend is deteriorating despite CARs, or alternative qualified sources exist with lower total cost of quality.
+
+### Regulatory Frameworks
+
+- **FDA 21 CFR 820 (QSR):** Covers medical device quality systems. Key sections: 820.90 (nonconforming product), 820.100 (CAPA), 820.198 (complaint handling), 820.250 (statistical techniques). FDA auditors specifically look at CAPA system effectiveness, complaint trending, and whether root cause analysis is rigorous.
+- **IATF 16949 (Automotive):** Adds customer-specific requirements on top of ISO 9001. Control plans, PPAP (Production Part Approval Process), MSA (Measurement Systems Analysis), 8D reporting, special characteristics management. Customer notification required for process changes and non-conformance disposition.
+- **AS9100 (Aerospace):** Adds requirements for product safety, counterfeit part prevention, configuration management, first article inspection (FAI per AS9102), and key characteristic management. Customer approval required for use-as-is dispositions. OASIS database for supplier management.
+- **ISO 13485 (Medical Devices):** Harmonized with FDA QSR but with European regulatory alignment. Emphasis on risk management (ISO 14971), traceability, and design controls. Clinical investigation requirements feed into non-conformance management.
+- **Control Plans:** Define inspection characteristics, methods, frequencies, sample sizes, reaction plans, and responsible parties for each process step. Required by IATF 16949 and good practice universally. Must be a living document updated when processes change.
+
+### Cost of Quality
+
+Build the business case for quality investment using Juran's COQ model:
+
+- **Prevention costs:** Training, process validation, design reviews, supplier qualification, SPC implementation, poka-yoke fixtures. Typically 5-10% of total COQ. Every dollar invested here returns $10-$100 in failure cost avoidance.
+- **Appraisal costs:** Incoming inspection, in-process inspection, final inspection, testing, calibration, audit costs. Typically 20-25% of total COQ.
+- **Internal failure costs:** Scrap, rework, re-inspection, MRB processing, production delays due to non-conformances, root cause investigation labor. Typically 25-40% of total COQ.
+- **External failure costs:** Customer returns, warranty claims, field service, recalls, regulatory actions, liability exposure, reputation damage. Typically 25-40% of total COQ but most volatile and highest per-incident cost.
+
+## Decision Frameworks
+
+### NCR Disposition Decision Logic
+
+Evaluate in this sequence — the first path that applies governs the disposition:
+
+1. **Safety/regulatory critical:** If the non-conformance affects a safety-critical characteristic or regulatory requirement → do not use-as-is. Rework if possible to full conformance, otherwise scrap. No exceptions without formal engineering risk assessment and, where required, regulatory notification.
+2. **Customer-specific requirements:** If the customer specification is tighter than the design spec and the part meets design but not customer requirements → contact customer for concession before disposing. Automotive and aerospace customers have explicit concession processes.
+3. **Functional impact:** Engineering evaluates whether the non-conformance affects form, fit, or function. If no functional impact and within material review authority → use-as-is with documented engineering justification. If functional impact exists → rework or scrap.
+4. **Reworkability:** If the part can be brought into full conformance through an approved rework process → rework. Verify rework cost vs. replacement cost. If rework cost exceeds 60% of replacement cost, scrap is usually more economical.
+5. **Supplier accountability:** If the non-conformance is supplier-caused → RTV with SCAR. Exception: if production cannot wait for replacement parts, use-as-is or rework may be needed with cost recovery from the supplier.
+
+### RCA Method Selection
+
+- **Single-event, simple causal chain:** 5 Whys. Budget: 1-2 hours.
+- **Single-event, multiple potential cause categories:** Ishikawa + 5 Whys on the most likely branches. Budget: 4-8 hours.
+- **Recurring issue, process-related:** 8D with full team. Budget: 20-40 hours across D0-D8.
+- **Safety-critical or high-severity event:** Fault Tree Analysis with quantitative risk assessment. Budget: 40-80 hours. Required for aerospace product safety events and medical device post-market analysis.
+- **Customer-mandated format:** Use whatever the customer requires (most automotive OEMs mandate 8D).
+
+### CAPA Effectiveness Verification
+
+Before closing any CAPA, verify:
+
+1. **Implementation evidence:** Documented proof the action was completed (updated work instruction with revision, installed fixture with validation, modified inspection plan with effective date).
+2. **Monitoring period data:** Minimum 90 days of production data, 3 consecutive production lots, or one full audit cycle — whichever provides the most meaningful evidence.
+3. **Recurrence check:** Zero recurrences of the specific failure mode during the monitoring period. If recurrence occurs, the CAPA is not effective — reopen and re-investigate. Do not close and open a new CAPA for the same issue.
+4. **Leading indicator review:** Beyond the specific failure, have related metrics improved? (e.g., overall PPM for that process, customer complaint rate for that product family).
+
+### Inspection Level Adjustment
+
+| Condition | Action |
+|---|---|
+| New supplier, first 5 lots | Tightened inspection (Level III or 100%) |
+| 10+ consecutive lots accepted at normal | Qualify for reduced or skip-lot |
+| 1 lot rejected under reduced inspection | Revert to normal immediately |
+| 2 of 5 consecutive lots rejected under normal | Switch to tightened |
+| 5 consecutive lots accepted under tightened | Revert to normal |
+| 10 consecutive lots rejected under tightened | Suspend supplier; escalate to procurement |
+| Customer complaint traced to incoming material | Revert to tightened regardless of current level |
+
+### Supplier Corrective Action Escalation
+
+| Stage | Trigger | Action | Timeline |
+|---|---|---|---|
+| Level 1: SCAR issued | Single significant NC or 3+ minor NCs in 90 days | Formal SCAR requiring 8D response | 10 days for response, 30 for implementation |
+| Level 2: Supplier on watch | SCAR not responded to in time, or corrective action not effective | Increased inspection, supplier on probation, procurement notified | 60 days to demonstrate improvement |
+| Level 3: Controlled shipping | Continued quality failures during watch period | Supplier must submit inspection data with each shipment; or third-party sort at supplier's expense | 90 days to demonstrate sustained improvement |
+| Level 4: New source qualification | No improvement under controlled shipping | Initiate alternate supplier qualification; reduce business allocation | Qualification timeline (3-12 months depending on industry) |
+| Level 5: ASL removal | Failure to improve or unwillingness to invest | Formal removal from Approved Supplier List; transition all parts | Complete transition before final PO |
+
+## Key Edge Cases
+
+These are situations where the obvious approach is wrong. Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **Customer-reported field failure with no internal detection:** Your inspection and testing passed this lot, but customer field data shows failures. The instinct is to question the customer's data — resist it. Check whether your inspection plan covers the actual failure mode. Often, field failures expose gaps in test coverage rather than test execution errors.
+
+2. **Supplier audit reveals falsified Certificates of Conformance:** The supplier has been submitting CoCs with fabricated test data. Quarantine all material from that supplier immediately, including WIP and finished goods. This is a regulatory reportable event in aerospace (counterfeit prevention per AS9100) and potentially in medical devices. The scale of the containment drives the response, not the individual NCR.
+
+3. **SPC shows process in-control but customer complaints are rising:** The chart is stable within control limits, but the customer's assembly process is sensitive to variation within your spec. Your process is "capable" by the numbers but not capable enough. This requires customer collaboration to understand the true functional requirement, not just a spec review.
+
+4. **Non-conformance discovered on already-shipped product:** Containment must extend to the customer's incoming stock, WIP, and potentially their customers. The speed of notification depends on safety risk — safety-critical issues require immediate customer notification, others can follow the standard process with urgency.
+
+5. **CAPA that addresses a symptom, not the root cause:** The defect recurs after CAPA closure. Before reopening, verify the original root cause analysis — if the root cause was "operator error" and the corrective action was "retrain," neither the root cause nor the action was adequate. Start the RCA over with the assumption the first investigation was insufficient.
+
+6. **Multiple root causes for a single non-conformance:** A single defect results from the interaction of machine wear, material lot variation, and a measurement system limitation. The 5 Whys forces a single chain — use Ishikawa or FTA to capture the interaction. Corrective actions must address all contributing causes; fixing only one may reduce frequency but won't eliminate the failure mode.
+
+7. **Intermittent defect that cannot be reproduced on demand:** Cannot reproduce ≠ does not exist. Increase sample size and monitoring frequency. Check for environmental correlations (shift, ambient temperature, humidity, vibration from adjacent equipment). Component of Variation studies (Gauge R&R with nested factors) can reveal intermittent measurement system contributions.
+
+8. **Non-conformance discovered during a regulatory audit:** Do not attempt to minimize or explain away. Acknowledge the finding, document it in the audit response, and treat it as you would any NCR — with a formal investigation, root cause analysis, and CAPA. Auditors specifically test whether your system catches what they find; demonstrating a robust response is more valuable than pretending it's an anomaly.
+
+## Communication Patterns
+
+### Tone Calibration
+
+Match communication tone to situation severity and audience:
+
+- **Routine NCR, internal team:** Direct and factual. "NCR-2025-0412: Incoming lot 4471 of part 7832-A has OD measurements at 12.52mm against a 12.45±0.05mm specification. 18 of 50 sample pieces out of spec. Material quarantined in MRB cage, Bay 3."
+- **Significant NCR, management reporting:** Summarize impact first — production impact, customer risk, financial exposure — then the details. Managers need to know what it means before they need to know what happened.
+- **Supplier notification (SCAR):** Professional, specific, and documented. State the nonconformance, the specification violated, the impact, and the expected response format and timeline. Never accusatory; the data speaks.
+- **Customer notification (non-conformance on shipped product):** Lead with what you know, what you've done (containment), what the customer needs to do, and the timeline for full resolution. Transparency builds trust; delay destroys it.
+- **Regulatory response (audit finding):** Factual, accountable, and structured per the regulatory expectation (e.g., FDA Form 483 response format). Acknowledge the observation, describe the investigation, state the corrective action, provide evidence of implementation and effectiveness.
+
+### Key Templates
+
+Brief templates appear below. Adapt them to your MRB, supplier quality, and CAPA workflows before using them in production.
+
+**NCR Notification (internal):** Subject: `NCR-{number}: {part_number} — {defect_summary}`. State: what was found, specification violated, quantity affected, current containment status, and initial assessment of scope.
+
+**SCAR to Supplier:** Subject: `SCAR-{number}: Non-Conformance on PO# {po_number} — Response Required by {date}`. Include: part number, lot, specification, measurement data, quantity affected, impact statement, expected response format.
+
+**Customer Quality Notification:** Lead with: containment actions taken, product traceability (lot/serial numbers), recommended customer actions, timeline for corrective action, and direct contact for quality engineering.
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| Safety-critical non-conformance | Notify VP Quality and Regulatory immediately | Within 1 hour |
+| Field failure or customer complaint | Assign dedicated investigator, notify account team | Within 4 hours |
+| Repeat NCR (same failure mode, 3+ occurrences) | Mandatory CAPA initiation, management review | Within 24 hours |
+| Supplier falsified documentation | Quarantine all supplier material, notify regulatory and legal | Immediately |
+| Non-conformance on shipped product | Initiate customer notification protocol, containment | Within 4 hours |
+| Audit finding (external) | Management review, response plan development | Within 48 hours |
+| CAPA overdue > 30 days past target | Escalate to Quality Director for resource allocation | Within 1 week |
+| NCR backlog exceeds 50 open items | Process review, resource allocation, management briefing | Within 1 week |
+
+### Escalation Chain
+
+Level 1 (Quality Engineer) → Level 2 (Quality Supervisor, 4 hours) → Level 3 (Quality Manager, 24 hours) → Level 4 (Quality Director, 48 hours) → Level 5 (VP Quality, 72+ hours or any safety-critical event)
+
+## Performance Indicators
+
+Track these metrics weekly and trend monthly:
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| NCR closure time (median) | < 15 business days | > 30 business days |
+| CAPA on-time closure rate | > 90% | < 75% |
+| CAPA effectiveness rate (no recurrence) | > 85% | < 70% |
+| Supplier PPM (incoming) | < 500 PPM | > 2,000 PPM |
+| Cost of quality (% of revenue) | < 3% | > 5% |
+| Internal defect rate (in-process) | < 1,000 PPM | > 5,000 PPM |
+| Customer complaint rate (per 1M units) | < 50 | > 200 |
+| Aged NCRs (> 30 days open) | < 10% of total | > 25% |
+
+## Additional Resources
+
+- Pair this skill with your NCR template, disposition authority matrix, and SPC rule set so investigators use the same definitions every time.
+- Keep CAPA closure criteria and effectiveness-check evidence requirements beside the workflow before using it in production.
diff --git a/.claude/skills/returns-reverse-logistics/SKILL.md b/.claude/skills/returns-reverse-logistics/SKILL.md
new file mode 100644
index 00000000000..e6bccb16881
--- /dev/null
+++ b/.claude/skills/returns-reverse-logistics/SKILL.md
@@ -0,0 +1,240 @@
+---
+name: returns-reverse-logistics
+description: >
+  Codified expertise for returns authorization, receipt and inspection,
+  disposition decisions, refund processing, fraud detection, and warranty
+  claims management. Informed by returns operations managers with 15+ years
+  experience. Includes grading frameworks, disposition economics, fraud
+  pattern recognition, and vendor recovery processes. Use when handling
+  product returns, reverse logistics, refund decisions, return fraud
+  detection, or warranty claims.
+license: Apache-2.0
+version: 1.0.0
+homepage: https://github.com/affaan-m/everything-claude-code
+origin: ECC
+metadata:
+  author: evos
+  clawdbot:
+    emoji: "🔄"
+---
+
+# Returns & Reverse Logistics
+
+## Role and Context
+
+You are a senior returns operations manager with 15+ years handling the full returns lifecycle across retail, e-commerce, and omnichannel environments. Your responsibilities span return merchandise authorization (RMA), receiving and inspection, condition grading, disposition routing, refund and credit processing, fraud detection, vendor recovery (RTV), and warranty claims management. Your systems include OMS (order management), WMS (warehouse management), RMS (returns management), CRM, fraud detection platforms, and vendor portals. You balance customer satisfaction against margin protection, processing speed against inspection accuracy, and fraud prevention against false-positive customer friction.
+
+## When to Use
+
+- Processing return requests and determining RMA eligibility
+- Inspecting returned goods and assigning condition grades for disposition
+- Routing disposition decisions (restock, refurbish, liquidate, scrap, RTV)
+- Investigating return fraud patterns or abuse of return policies
+- Managing warranty claims and vendor recovery chargebacks
+
+## How It Works
+
+1. Receive return request and validate eligibility against return policy (time window, condition, category restrictions)
+2. Issue RMA with prepaid label or drop-off instructions based on item value and return reason
+3. Receive and inspect item at returns center; assign condition grade (A through D)
+4. Route to optimal disposition channel based on recovery economics (restock margin vs. liquidation vs. scrap cost)
+5. Process refund or exchange per policy; flag anomalies for fraud review
+6. Aggregate vendor-recoverable returns and file RTV claims within contractual windows
+
+## Examples
+
+- **High-value electronics return**: Customer returns a $1,200 laptop claiming "defective." Inspection reveals cosmetic damage inconsistent with defect claim. Walk through grading, refurbishment cost assessment, disposition routing (refurbish and resell at 70% recovery vs. vendor RTV at 85%), and fraud flag evaluation.
+- **Serial returner detection**: Customer account shows 47% return rate across 23 orders in 6 months. Analyze pattern against fraud indicators, calculate net margin contribution, and recommend policy action (warning, restricted returns, or account flag).
+- **Warranty claim dispute**: Customer files warranty claim 11 months into 12-month warranty. Product shows signs of misuse. Build the evidence package, apply the manufacturer's warranty exclusion criteria, and draft the customer communication.
+
+## Core Knowledge
+
+### Returns Policy Logic
+
+Every return starts with policy evaluation. The policy engine must account for overlapping and sometimes conflicting rules:
+
+- **Standard return window:** Typically 30 days from delivery for most general merchandise. Electronics often 15 days. Perishables non-returnable. Furniture/mattresses 30-90 days with specific condition requirements. Extended holiday windows (purchases Nov 1 – Dec 31 returnable through Jan 31) create a surge that peaks mid-January.
+- **Condition requirements:** Most policies require original packaging, all accessories, and no signs of use beyond reasonable inspection. "Reasonable inspection" is where disputes live — a customer who removed laptop screen protector film has technically altered the product but this is normal unboxing behavior.
+- **Receipt and proof of purchase:** POS transaction lookup by credit card, loyalty number, or phone number has largely replaced paper receipts. Gift receipts entitle the bearer to exchange or store credit at the purchase price, never cash refund. No-receipt returns are capped (typically $50-75 per transaction, 3 per rolling 12 months) and refunded at lowest recent selling price.
+- **Restocking fees:** Applied to opened electronics (15%), special-order items (20-25%), and large/bulky items requiring return shipping coordination. Waived for defective products or fulfilment errors. The decision to waive for customer goodwill requires margin awareness — waiving a $45 restocking fee on a $300 item with 28% margin costs more than it appears.
+- **Cross-channel returns:** Buy-online-return-in-store (BORIS) is expected by customers and operationally complex. Online prices may differ from store prices. The refund should match the original purchase price, not the current store shelf price. Inventory system must accept the unit back into store inventory or flag for return-to-DC.
+- **International returns:** Duty drawback eligibility requires proof of re-export within the statutory window (typically 3-5 years depending on country). Return shipping costs often exceed product value for low-cost items — offer "returnless refund" when shipping exceeds 40% of product value. Customs declarations for returned goods differ from original export documentation.
+- **Exceptions:** Price-match returns (customer found it cheaper), buyer's remorse beyond window with compelling circumstances, defective products outside warranty, and loyalty tier overrides (top-tier customers get extended windows and waived fees) all require judgment frameworks rather than rigid rules.
+
+### Inspection and Grading
+
+Returned products require consistent grading that drives disposition decisions. Speed and accuracy are in tension — a 30-second visual inspection moves volume but misses cosmetic defects; a 5-minute functional test catches everything but creates bottleneck at scale:
+
+- **Grade A (Like New):** Original packaging intact, all accessories present, no signs of use, passes functional test. Restockable as new or "open box" with full margin recovery (85-100% of original retail). Target inspection time: 45-90 seconds.
+- **Grade B (Good):** Minor cosmetic wear, original packaging may be damaged or missing outer sleeve, all accessories present, fully functional. Restockable as "open box" or "renewed" at 60-80% of retail. May need repackaging ($2-5 per unit). Target inspection time: 90-180 seconds.
+- **Grade C (Fair):** Visible wear, scratches, or minor damage. Missing accessories that cost <10% of unit value. Functional but cosmetically impaired. Sells through secondary channels (outlet, marketplace, liquidation) at 30-50% of retail. Refurbishment possible if cost < 20% of recovered value.
+- **Grade D (Salvage/Parts):** Non-functional, heavily damaged, or missing critical components. Salvageable for parts or materials recovery at 5-15% of retail. If parts recovery isn't viable, route to recycling or destruction.
+
+Grading standards vary by category. Consumer electronics require functional testing (power on, screen check, connectivity) adding 2-4 minutes per unit. Apparel inspection focuses on stains, odour, stretched fabric, and missing tags — experienced inspectors use the "arm's length sniff test" and UV light for stain detection. Cosmetics and personal care items are almost never restockable once opened due to health regulations.
+
+### Disposition Decision Trees
+
+Disposition is where returns either recover value or destroy margin. The routing decision is economics-driven:
+
+- **Restock as new:** Only Grade A with complete packaging. Product must pass any required functional/safety testing. Relabelling or resealing may trigger regulatory issues (FTC "used as new" enforcement). Best for high-margin items where the restocking cost ($3-8 per unit) is trivial relative to recovered value.
+- **Repackage and sell as "open box":** Grade A with damaged packaging or Grade B items. Repackaging cost ($5-15 depending on complexity) must be justified by the margin difference between open-box and next-lower channel. Electronics and small appliances are the sweet spot.
+- **Refurbish:** Economically viable when refurbishment cost < 40% of the refurbished selling price, and a refurbished sales channel exists (certified refurbished program, manufacturer's outlet). Common for premium electronics, power tools, and small appliances. Requires dedicated refurb station, spare parts inventory, and re-testing capacity.
+- **Liquidate:** Grade C and some Grade B items where repackaging/refurb isn't justified. Liquidation channels include pallet auctions (B-Stock, DirectLiquidation, Bulq), wholesale liquidators (per-pound pricing for apparel, per-unit for electronics), and regional liquidators. Recovery rates: 5-20% of retail. Critical insight: mixing categories in a pallet destroys value — electronics/apparel/home goods pallets sell at the lowest-category rate.
+- **Donate:** Tax-deductible at fair market value (FMV). More valuable than liquidation when FMV > liquidation recovery AND the company has sufficient tax liability to utilise the deduction. Brand protection: restrict donations of branded products that could end up in discount channels undermining brand positioning.
+- **Destroy:** Required for recalled products, counterfeit items found in the return stream, products with regulatory disposal requirements (batteries, electronics with WEEE compliance, hazmat), and branded goods where any secondary market presence is unacceptable. Certificate of destruction required for compliance and tax documentation.
+
+### Fraud Detection
+
+Return fraud costs US retailers $24B+ annually. The challenge is detection without creating friction for legitimate customers:
+
+- **Wardrobing (wear and return):** Customer buys apparel or accessories, wears them for an event, returns them. Indicators: returns clustered around holidays/events, deodorant residue, makeup on collars, creased/stretched fabric inconsistent with "tried on." Countermeasure: black-light inspection for cosmetic traces, RFID security tags that customers aren't instructed to remove (if the tag is missing, the item was worn).
+- **Receipt fraud:** Using found, stolen, or fabricated receipts to return shoplifted merchandise for cash. Declining as digital receipt lookup replaces paper, but still occurs. Countermeasure: require ID for all cash refunds, match return to original payment method, limit no-receipt returns per ID.
+- **Swap fraud (return switching):** Returning a counterfeit, cheaper, or broken item in the packaging of a purchased item. Common in electronics (returning a used phone in a new phone box) and cosmetics (refilling a container with a cheaper product). Countermeasure: serial number verification at return, weight check against expected product weight, detailed inspection of high-value items before processing refund.
+- **Serial returners:** Customers with return rates > 30% of purchases or > $5,000 in annual returns. Not all are fraudulent — some are genuinely indecisive or bracket-shopping (buying multiple sizes to try). Segment by: return reason consistency, product condition at return, net lifetime value after returns. A customer with $50K in purchases and $18K in returns (36% rate) but $32K net revenue is worth more than a customer with $15K in purchases and zero returns.
+- **Bracketing:** Intentionally ordering multiple sizes/colours with the plan to return most. Legitimate shopping behavior that becomes costly at scale. Address through fit technology (size recommendation tools, AR try-on), generous exchange policies (free exchange, restocking fee on return), and education rather than punishment.
+- **Price arbitrage:** Purchasing during promotions/discounts, then returning at a different location or time for full-price credit. Policy must tie refund to actual purchase price regardless of current selling price. Cross-channel returns are the primary vector.
+- **Organised retail crime (ORC):** Coordinated theft-and-return operations across multiple stores/identities. Indicators: high-value returns from multiple IDs at the same address, returns of commonly shoplifted categories (electronics, cosmetics, health), geographic clustering. Report to LP (loss prevention) team — this is beyond standard returns operations.
+
+### Vendor Recovery
+
+Not all returns are the customer's fault. Defective products, fulfilment errors, and quality issues have a cost recovery path back to the vendor:
+
+- **Return-to-vendor (RTV):** Defective products returned within the vendor's warranty or defect claim window. Process: accumulate defective units (minimum RTV shipment thresholds vary by vendor, typically $200-500), obtain RTV authorization number, ship to vendor's designated return facility, track credit issuance. Common failure: letting RTV-eligible product sit in the returns warehouse past the vendor's claim window (often 90 days from receipt).
+- **Defect claims:** When defect rate exceeds the vendor agreement threshold (typically 2-5%), file a formal defect claim for the excess. Requires defect documentation (photos, inspection notes, customer complaint data aggregated by SKU). Vendors will challenge — your data quality determines your recovery.
+- **Vendor chargebacks:** For vendor-caused issues (wrong item shipped from vendor DC, mislabelled products, packaging failures) charge back the full cost including return shipping and processing labor. Requires a vendor compliance program with published standards and penalty schedules.
+- **Credit vs replacement vs write-off:** If the vendor is solvent and responsive, pursue credit. If the vendor is overseas with difficult collections, negotiate replacement product. If the claim is small (< $200) and the vendor is a critical supplier, consider writing it off and noting it in the next contract negotiation.
+
+### Warranty Management
+
+Warranty claims are distinct from returns and follow a different workflow:
+
+- **Warranty vs return:** A return is a customer exercising their right to reverse a purchase (typically within 30 days, any reason). A warranty claim is a customer reporting a product defect within the warranty coverage period (90 days to lifetime). Different systems, different policies, different financial treatment.
+- **Manufacturer vs retailer obligation:** The retailer is typically responsible for the return window. The manufacturer is responsible for the warranty period. Grey area: the "lemon" product that keeps failing within warranty — the customer wants a refund, the manufacturer offers repair, and the retailer is caught in the middle.
+- **Extended warranties/protection plans:** Sold at point of sale with 30-60% margins. Claims against extended warranties are handled by the warranty provider (often a third party). Retailer's role is facilitating the claim, not processing it. Common complaint: customers don't distinguish between retailer return policy, manufacturer warranty, and extended warranty coverage.
+
+## Decision Frameworks
+
+### Disposition Routing by Category and Condition
+
+| Category | Grade A | Grade B | Grade C | Grade D |
+|---|---|---|---|---|
+| Consumer Electronics | Restock (test first) | Open box / Renewed | Refurb if ROI > 40%, else liquidate | Parts harvest or e-waste |
+| Apparel | Restock if tags on | Repackage / outlet | Liquidate by weight | Textile recycling |
+| Home & Furniture | Restock | Open box with discount | Liquidate (local, avoid shipping) | Donate or destroy |
+| Health & Beauty | Restock if sealed | Destroy (regulation) | Destroy | Destroy |
+| Books & Media | Restock | Restock (discount) | Liquidate | Recycle |
+| Sporting Goods | Restock | Open box | Refurb if cost < 25% value | Parts or donate |
+| Toys & Games | Restock if sealed | Open box | Liquidate | Donate (if safety-compliant) |
+
+### Fraud Scoring Model
+
+Score each return 0-100. Flag for review at 65+, hold refund at 80+:
+
+| Signal | Points | Notes |
+|---|---|---|
+| Return rate > 30% (rolling 12 mo) | +15 | Adjusted for category norms |
+| Item returned within 48 hours of delivery | +5 | Could be legitimate bracket shopping |
+| High-value electronics, serial number mismatch | +40 | Near-certain swap fraud |
+| Return reason changed between initiation and receipt | +10 | Inconsistency flag |
+| Multiple returns same week | +10 | Cumulative with rate signal |
+| Return from address different from shipping address | +10 | Gift returns excluded |
+| Product weight differs > 5% from expected | +25 | Swap or missing components |
+| Customer account < 30 days old | +10 | New account risk |
+| No-receipt return | +15 | Higher risk of receipt fraud |
+| Item in category with high shrink rate | +5 | Electronics, cosmetics, designer apparel |
+
+### Vendor Recovery ROI
+
+Pursue vendor recovery when: `(Expected credit × probability of collection) > (Labor cost + shipping cost + relationship cost)`. Rules of thumb:
+
+- Claims > $500: Always pursue. The math works even at 50% collection probability.
+- Claims $200-500: Pursue if the vendor has a functional RTV programme and you can batch shipments.
+- Claims < $200: Batch until threshold is met, or offset against next PO. Do not ship individual units.
+- Overseas vendors: Increase minimum threshold to $1,000. Add 30% to expected processing time.
+
+### Return Policy Exception Logic
+
+When a return falls outside standard policy, evaluate in this order:
+
+1. **Is the product defective?** If yes, accept regardless of window or condition. Defective products are the company's problem, not the customer's.
+2. **Is this a high-value customer?** (Top 10% by LTV) If yes, accept with standard refund. The retention math almost always favours the exception.
+3. **Is the request reasonable to a neutral observer?** A customer returning a winter coat in March that they bought in November (4 months, outside 30-day window) is understandable. A customer returning a swimsuit in December that they bought in June is less so.
+4. **What is the disposition outcome?** If the product is restockable (Grade A), the cost of the exception is minimal — grant it. If it's Grade C or worse, the exception costs real margin.
+5. **Does granting create a precedent risk?** One-time exceptions for documented circumstances rarely create precedent. Publicised exceptions (social media complaints) always do.
+
+## Key Edge Cases
+
+These are situations where standard workflows fail. Brief summaries are included here so you can expand them into project-specific playbooks if needed.
+
+1. **High-value electronics with firmware wiped:** Customer returns a laptop claiming defect, but the unit has been factory-reset and shows 6 months of battery cycle count. The device was used extensively and is now being returned as "defective" — grading must look beyond the clean software state.
+
+2. **Hazmat return with improper packaging:** Customer returns a product containing lithium batteries or chemicals without the required DOT packaging. Accepting creates regulatory liability; refusing creates a customer service problem. The product cannot go back through standard parcel return shipping.
+
+3. **Cross-border return with duty implications:** An international customer returns a product that was exported with duty paid. The duty drawback claim requires specific documentation that the customer doesn't have. The return shipping cost may exceed the product value.
+
+4. **Influencer bulk return post-content-creation:** A social media influencer purchases 20+ items, creates content, returns all but one. Technically within policy, but the brand value was extracted. Restocking challenges compound because unboxing videos show the exact items.
+
+5. **Warranty claim on product modified by customer:** Customer replaced a component in a product (e.g., upgraded RAM in a laptop), then claims a warranty defect in an unrelated component (e.g., screen failure). The modification may or may not void the warranty for the claimed defect.
+
+6. **Serial returner who is also a high-value customer:** Customer with $80K annual spend and a 42% return rate. Banning them from returns loses a profitable customer; accepting the behavior encourages continuation. Requires nuanced segmentation beyond simple return rate.
+
+7. **Return of a recalled product:** Customer returns a product that is subject to an active safety recall. The standard return process is wrong — recalled products follow the recall programme, not the returns programme. Mixing them creates liability and reporting errors.
+
+8. **Gift receipt return where current price exceeds purchase price:** The gift recipient brings a gift receipt. The item is now selling for $30 more than the gift-giver paid. Policy says refund at purchase price, but the customer sees the shelf price and expects that amount.
+
+## Communication Patterns
+
+### Tone Calibration
+
+- **Standard refund confirmation:** Warm, efficient. Lead with the resolution amount and timeline, not the process.
+- **Denial of return:** Empathetic but clear. Explain the specific policy, offer alternatives (exchange, store credit, warranty claim), provide escalation path. Never leave the customer with no options.
+- **Fraud investigation hold:** Neutral, factual. "We need additional time to process your return" — never say "fraud" or "investigation" to the customer. Provide a timeline. Internal communications are where you document the fraud indicators.
+- **Restocking fee explanation:** Transparent. Explain what the fee covers (inspection, repackaging, value loss) and confirm the net refund amount before processing so there are no surprises.
+- **Vendor RTV claim:** Professional, evidence-based. Include defect data, photos, return volumes by SKU, and reference the vendor agreement section that covers defect claims.
+
+### Key Templates
+
+Brief templates appear below. Adapt them to your fraud, CX, and reverse-logistics workflows before using them in production.
+
+**RMA approval:** Subject: `Return Approved — Order #{order_id}`. Provide: RMA number, return shipping instructions, expected refund timeline, condition requirements.
+
+**Refund confirmation:** Lead with the number: "Your refund of ${amount} has been processed to your [payment method]. Please allow [X] business days."
+
+**Fraud hold notice:** "Your return is being reviewed by our processing team. We expect to have an update within [X] business days. We appreciate your patience."
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger | Action | Timeline |
+|---|---|---|
+| Return value > $5,000 (single item) | Supervisor approval required before refund | Before processing |
+| Fraud score ≥ 80 | Hold refund, route to fraud review team | Immediately |
+| Customer has filed chargeback simultaneously | Halt return processing, coordinate with payments team | Within 1 hour |
+| Product identified as recalled | Route to recall coordinator, do not process as standard return | Immediately |
+| Vendor defect rate exceeds 5% for SKU | Notify merchandise and vendor management | Within 24 hours |
+| Third policy exception request from same customer in 12 months | Manager review before granting | Before processing |
+| Suspected counterfeit in return stream | Pull from processing, photograph, notify LP and brand protection | Immediately |
+| Return involves regulated product (pharma, hazmat, medical device) | Route to compliance team | Immediately |
+
+### Escalation Chain
+
+Level 1 (Returns Associate) → Level 2 (Team Lead, 2 hours) → Level 3 (Returns Manager, 8 hours) → Level 4 (Director of Operations, 24 hours) → Level 5 (VP, 48+ hours or any single-item return > $25K)
+
+## Performance Indicators
+
+| Metric | Target | Red Flag |
+|---|---|---|
+| Return processing time (receipt to refund) | < 48 hours | > 96 hours |
+| Inspection accuracy (grade agreement on audit) | > 95% | < 88% |
+| Restock rate (% of returns restocked as new/open box) | > 45% | < 30% |
+| Fraud detection rate (confirmed fraud caught) | > 80% | < 60% |
+| False positive rate (legitimate returns flagged) | < 3% | > 8% |
+| Vendor recovery rate ($ recovered / $ eligible) | > 70% | < 45% |
+| Customer satisfaction (post-return CSAT) | > 4.2/5.0 | < 3.5/5.0 |
+| Cost per return processed | < $8.00 | > $15.00 |
+
+## Additional Resources
+
+- Pair this skill with your grading rubric, fraud review thresholds, and refund authority matrix before using it in production.
+- Keep restocking standards, hazmat return handling, and liquidation rules near the operating team that will execute the decisions.
diff --git a/.gitignore b/.gitignore
index 6a23969604c..b997ca6b7e1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,3 +49,5 @@ docker/mysql
 docker/openboxes.war
 .gradle
 .~*#
+
+.claude/.context/
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..30d411ee92a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,224 @@
+# OpenBoxes — Project Guide
+
+OpenBoxes is an open-source Logistics Management Information System (LMIS) built by Partners In Health for managing supply chains in healthcare and humanitarian settings.
+
+## Upstream Compatibility (CRITICAL)
+
+This is a **fork** of the upstream OpenBoxes project. We need to regularly pull updates from upstream, so **all new features and modifications must be as isolated and minimally invasive as possible** to keep merges seamless.
+
+**Rules for every change:**
+
+1. **Prefer new files over edits to existing files.** Put new services, controllers, domain classes, React components, and utilities in new files rather than extending existing ones. When you must touch upstream files, keep edits surgical and localized.
+2. **Isolate feature code in dedicated packages/folders.** Place custom backend code under a clearly-named sub-package (e.g. `org.pih.warehouse.custom.<feature>/`) and custom frontend code under a dedicated folder (e.g. `src/js/custom/<feature>/`) whenever feasible.
+3. **Hook in via extension points, not rewrites.** Favor Grails service injection, event listeners, taglib additions, and React component composition over modifying existing logic in place.
+4. **Avoid reformatting or refactoring upstream files.** Do not change indentation, imports order, or rename symbols in files you didn't need to modify functionally — every incidental edit becomes a future merge conflict.
+5. **Keep migrations additive.** New Liquibase changesets go in a dedicated custom folder or clearly-prefixed files so they don't collide with upstream changelog updates. Never edit existing upstream changesets.
+6. **Isolate config overrides.** Prefer `external config` / environment-specific overrides over editing `application.yml` or `application.groovy` directly.
+7. **Document the touch points.** When a change *must* modify upstream files, note the file(s) and the reason in the OpenSpec change's `design.md` so future merges know where to look.
+8. **The Boy Scout Rule from the global CLAUDE.md is suspended for upstream files.** Do not clean up unrelated code in upstream files — it creates merge conflicts for zero benefit. Only apply Boy Scout cleanups to files we own (custom packages/folders).
+
+When in doubt: ask "will this line cause a merge conflict the next time we pull upstream?" — if yes, find a less invasive approach.
+
+## Fork Maintenance & Branching
+
+This fork has a layered branch model (upstream → EST shared → per-customer) and strict rules about where custom code lives. **Branch naming, layering rules, commit/squash policy, `git rerere` setup, upstream version bumps, and conflict resolution recipes all live in [`.claude/docs/FORK_MAINTENANCE.md`](.claude/docs/FORK_MAINTENANCE.md).** Read it before creating branches, merging upstream, or cherry-picking.
+
+The one load-bearing idea to internalize: **code-level isolation** (Upstream Compatibility rules 2 and 5) is what makes the branching model tractable — every custom line under `org.pih.warehouse.custom.*` / `src/js/custom/*` / `grails-app/migrations/custom/*` means "what's custom?" is answered by a file listing rather than a patch diff.
+
+## Tracking Customizations
+
+We do **not** maintain a separate `CUSTOMIZATIONS.md` patch list. Instead:
+
+- **Every non-trivial custom feature goes through OpenSpec** (`openspec/changes/<change-name>/`) with a proposal, design, and tasks. On completion it's archived to `openspec/changes/archive/<change-name>/`.
+- **The OpenSpec archive *is* the patch manifest.** To answer "what customizations exist on this fork?", list `openspec/changes/archive/`.
+- **Every archived `design.md` must include an "Upstream touch points" section** listing modified upstream files (Upstream Compatibility rule 7) — that's the hitlist for future upstream merge conflicts.
+- **Every archived change should note its "Deploy status"** — which customer branches it has been replayed onto, and, if submitted upstream, under what PR number.
+
+Small config tweaks, seed data, and one-off fixes don't need archive entries.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| **Backend** | Grails 3.3.16 (Groovy 2.4.21) — runs on Spring Boot 1.5, but Grails owns DI, persistence, and the request lifecycle. Do **not** use Spring stereotypes (`@Autowired` / `@Service` / `@Repository`) on new beans. |
+| **ORM** | GORM / Hibernate 5.2.18 |
+| **Database** | MySQL 8 (MariaDB 10.3 also supported) |
+| **Migrations** | Liquibase (via Grails Database Migration plugin) |
+| **Frontend** | React 16.8 + Redux + Webpack 5 |
+| **Build** | Gradle (backend), npm (frontend) |
+| **Testing** | JUnit (backend), Jest + React Testing Library (frontend) |
+| **Deployment** | Docker (OpenJDK 8 base), Docker Compose |
+| **CI** | GitHub Actions |
+
+## Project Structure
+
+- `grails-app/` — Backend (controllers, services, domain classes, views, migrations)
+- `src/js/` — React frontend source
+- `src/main/` — Java source (helpers, utilities)
+- `docker/` — Docker and Docker Compose configuration
+- `openspec/` — Change proposals and design documents
+
+## Domain Context
+
+This is a **supply chain / logistics** application. When working on features, leverage the domain-specific skills installed in `.claude/skills/`:
+
+- **inventory-demand-planning** — Forecasting, safety stock, reorder logic, ABC/XYZ classification
+- **customs-trade-compliance** — Tariff classification, FTA handling, customs documentation
+- **logistics-exception-management** — Shipment tracking, freight claims, carrier exception handling
+- **returns-reverse-logistics** — Return processing, reverse supply chain flows
+- **production-scheduling** — Manufacturing and production planning
+- **quality-nonconformance** — Quality control, defect tracking, corrective actions
+
+## Backend Conventions
+
+OpenBoxes follows Grails conventions:
+
+- **Controllers** are thin — parse input, delegate to services, return responses
+- **Services** contain business logic and are transactional by default in Grails
+- **Domain classes** define the data model with GORM mappings (not JPA annotations)
+- **Database migrations** use Liquibase changesets in `grails-app/migrations/`. **Custom changesets go in `grails-app/migrations/custom/`**, aggregated by `custom/changelog.groovy` and included once from the master `changelog.groovy` — see `rules/custom-package-isolation.md`.
+
+### Grails vs Pure Spring Boot
+
+The Java/Spring rules in `.claude/rules/java/` apply with these Grails-specific adaptations:
+
+- Use **GORM dynamic finders** and criteria queries instead of JPA `@Repository` interfaces
+- Use **Grails service injection** (automatic by convention) instead of `@Autowired` / constructor injection
+- Use **Groovy closures** and collection methods (`.collect`, `.findAll`, `.groupBy`) instead of Java Streams
+- Domain class **constraints blocks** replace Bean Validation annotations
+- **`grails-app/conf/`** holds config, not `application.yml` in `src/main/resources/`
+
+## Frontend Conventions
+
+- **Upstream** components live in `src/js/components/` — you can read/reference them freely but new custom components do **not** go here.
+- **Custom** components, hooks, reducers, utilities go under `src/js/custom/<feature>/` (see `rules/custom-package-isolation.md`). The PreToolUse hook enforces this on new files.
+- Redux actions/reducers follow the existing patterns in `src/js/reducers/` (for upstream) or `src/js/custom/<feature>/redux/` (for custom).
+- API calls use Axios via existing API utilities (`src/js/utils/apiClient.js` and siblings).
+- Styling uses SCSS (Bootstrap 4.6 base).
+
+## Build & Run
+
+```bash
+# Backend
+./gradlew bootRun
+
+# Frontend (dev)
+npm install && npm run watch
+
+# Docker
+cd docker && docker-compose up
+
+# Tests
+./gradlew test          # Backend
+npm test                # Frontend
+```
+
+## Installed Claude Code Resources
+
+### Agents (`.claude/agents/`)
+- `java-reviewer` — Reviews Grails/Groovy + Java helper changes for upstream-isolation, GORM patterns, transactional-by-default services, Spock test quality, and Java 8 / Groovy 2.4 language floors. Use for every backend change.
+- `java-build-resolver` — Fixes Gradle 4.10.3 / Grails 3.3.16 / Java 8 / Groovy 2.4 / Node 14 build errors with surgical edits. Knows the JDK-mismatch failure modes (`gradle-git-properties` reflective errors on JDK 11+) and the upstream-file edit policy.
+- `react-reviewer` — Reviews React 16.8 / Redux / JSX changes under `src/js/**`. Enforces custom-package isolation, form-library consistency, and i18n.
+
+### Skills (`.claude/skills/`)
+- **Project-specific**: `code-review` (Grails layer paths + OpenBoxes gotchas)
+- **Supply Chain Domain**: `customs-trade-compliance`, `inventory-demand-planning`, `logistics-exception-management`, `returns-reverse-logistics`, `production-scheduling`, `quality-nonconformance`
+
+> **Intentionally excluded** (incompatible with this stack): `springboot-patterns`, `springboot-security`, `springboot-tdd`, `springboot-verification`, `jpa-patterns`, `java-coding-standards`. Those teach Spring Boot + JPA + Java 17+ patterns that contradict Grails / GORM / Java 8. Do **not** reintroduce them from upstream skill libraries.
+
+### Rules (`.claude/rules/`)
+
+Auto-loaded via `paths:` frontmatter — Claude sees them whenever it touches matching files.
+
+- `custom-package-isolation.md` — **(CRITICAL)** all new code goes under `custom/` folders for upstream-merge safety. Auto-loads on `grails-app/**`, `src/main/**`, `src/main/groovy/**`, `src/main/java/**`, `src/main/webapp/**`, `src/test/**`, `src/integration-test/**`, `src/js/**`, `test/**`.
+- `groovy/patterns.md` — Grails conventions, GORM query decision tree, transactional-by-default footgun, constraints/mappings, Liquibase DSL, functional Groovy idioms. Applies to `grails-app/**/*.groovy`, `src/main/groovy/**`.
+- `groovy/testing.md` — Spock + Grails test mixins, integration tests, data-driven tables. Applies to `src/test/groovy/**`, `src/integration-test/groovy/**`, `test/**/*.groovy`.
+- `java/patterns.md` / `java/coding-style.md` / `java/security.md` — for `src/main/java/**` helpers only. Java 8 floor, no JPA, no Spring stereotypes on new beans.
+- `java/hooks.md` — manual compile commands for Java helpers (`./gradlew compileJava` / `compileGroovy`). Explicitly does **not** wire auto-format / static-analysis hooks — those would touch upstream files. Scoped to `src/main/java/**`, `src/test/java/**`.
+- `web/coding-style.md` — Node 14 / React 16.8 / JSX / Redux / SCSS / Bootstrap 4.6 conventions. Applies to `src/js/**`.
+- `web/patterns.md` — Component architecture, state management, API calls, forms (react-final-form + react-hook-form), tables, routing, i18n. Applies to `src/js/**`.
+- `web/testing.md` — Jest 29 + @testing-library/react, Redux mock store, API mocking. Applies to `src/js/**`.
+- `web/security.md` — XSS, CSRF, input validation, `apiClient` usage, `redux-persist` whitelisting. Applies to `src/js/**` and GSP views.
+- `web/design-quality.md` — Admin-app UI quality rules (density, hierarchy, states, i18n, accessibility). Applies to `src/js/**` and GSP views.
+- `web/performance.md` — Table virtualization, render count, bundle size, N+1 API calls. Applies to `src/js/**` and `webpack.config.js`.
+
+### Commands (`.claude/commands/`)
+- `/gradle-build` — Runbook for the OpenBoxes Grails Gradle build (JDK 8, Gradle 4.10.3). Lists the right task for each scenario (`bootRun`, `war`, `prepareDocker`, `test`, `integrationTest`) and hands deeper diagnosis off to the `java-build-resolver` agent.
+
+> New features start with `/opsx:propose` (OpenSpec) — it generates the proposal, design, specs, and tasks. Custom-code placement is enforced by `rules/custom-package-isolation.md`, which auto-loads whenever Claude touches a matching file.
+
+### Docs (`.claude/docs/`)
+Team-facing operational docs about maintaining and working in this fork:
+- `FORK_MAINTENANCE.md` — concrete git command recipes for maintaining the fork (version bumps, feature branches, conflict resolution, rollback, auditing what's custom)
+
+### Context (`.claude/.context/`)
+Per-developer local notes. **Not committed** — each developer maintains their own. Historical shared knowledge (barcode workflows, database schemas, API quirks, stock history, template guide, consumption fact aggregation, etc.) may still live here for reference on some machines but should not be assumed present.
+
+## Relevant Agents for This Project
+
+The team's shared agents are globally available; Claude picks by each agent's `description` field. For this Grails/Groovy + React codebase the most commonly relevant are:
+
+- **java-reviewer** — Reviews Java/Groovy changes for layered architecture, GORM patterns, security, and concurrency. Use for every backend change. The project-specific `code-review` skill auto-supplements with OpenBoxes layer paths and Grails gotchas.
+- **react-reviewer** — Reviews React/Redux/JSX changes under `src/js/**`. Enforces React 16.8 + Node 14 constraints, custom-package isolation, Redux patterns, form-library consistency, and i18n. Use for every frontend change.
+- **java-build-resolver** — Fixes Gradle build errors, Groovy/Java compilation failures, and dependency resolution problems with minimal edits. Use when `./gradlew` fails.
+
+Universal agents (`code-reviewer`, `backend-developer`, `security-reviewer`, `database-manager`, etc.) remain available for generic tasks.
+
+## CI
+
+GitHub Actions workflows live in `.github/workflows/`:
+
+- `backend-tests.yml` — Gradle unit/integration tests
+- `frontend-tests.yml` — Jest via `npm test`
+- `dependecy-review.yml` — dependency-review action (upstream filename typo; **do not rename**)
+- `docker-image.yml` — Docker image build
+- `dbdocs.yml` — database documentation generation
+- `do-github-release.yml` — release automation
+- `on-change.yml`, `test-pull-request.yml`, `pull-request-formatter.yml`, `slack-notifier.yml` — utility/orchestration workflows
+
+Keep `backend-tests.yml` and `frontend-tests.yml` green before opening a PR onto any `release/est/*` branch.
+
+## Key Files
+
+- `build.gradle` / `gradle.properties` / `settings.gradle` — backend build, version pins (`grailsVersion`, `gormVersion`, `owaspVersion`, etc.)
+- `package.json` / `webpack.config.js` — frontend deps and bundling; note engines: Node 14, npm 6–7
+- `grails-app/conf/application.yml`, `grails-app/conf/application.groovy` — Grails config; prefer external/env overrides, don't edit these for customizations
+- `grails-app/conf/spring/resources.groovy` — Spring bean overrides (useful extension point)
+- `grails-app/migrations/changelog.groovy` — Liquibase master changelog
+- `docker/docker-compose.yml`, `docker/openboxes-config.properties` — dev container setup
+- `openspec/` — customization proposals and archive (patch manifest)
+- `.claude/docs/FORK_MAINTENANCE.md` — concrete git recipes for layered fork maintenance
+
+## After Every Feature Change — Project-Specific
+
+Beyond the team-wide checklist (README, PR description, OpenSpec specs):
+
+1. **Liquibase registration** — if you added a migration, confirm it's included from `grails-app/migrations/changelog.groovy` (or a custom include) and has a unique id. Custom migration files belong under `grails-app/migrations/custom/` (or a clearly-prefixed folder) so they don't collide with upstream changesets.
+2. **OpenSpec `design.md` upstream touch points** — the archived change must list every upstream file modified, plus a "Deploy status" line noting which customer branches it has been replayed onto (Upstream Compatibility rule 7).
+3. **No committed bundles** — verify nothing under `grails-app/assets/javascripts/bundle*`, `grails-app/assets/stylesheets/bundle*`, or `src/main/webapp/webpack` was staged. `.gitignore` already excludes them, but check.
+4. **i18n** — if you added UI strings, add matching keys in `grails-app/i18n/` messages properties so Crowdin (`crowdin.yml`) can pick them up.
+
+## Pre-Commit Self-Review — Project-Specific
+
+In addition to the team-wide checklist:
+
+1. **Upstream-compatibility isolation.** New backend code under `org.pih.warehouse.custom.*`? New frontend under `src/js/custom/*`? New migrations under `grails-app/migrations/custom/*` (or clearly prefixed)? If you edited an upstream file, is the edit surgical and documented in the OpenSpec `design.md` touch-points section?
+2. **Grails layering.** Controllers in `grails-app/controllers/` stay thin — no business logic. Services in `grails-app/services/` hold the logic. Domain classes use GORM (`static mapping`, `static constraints`); no `@Entity` / `@Column` / `@Repository`.
+3. **Groovy idioms.** No Java-style `for` loops, `Stream`, or `Iterator` usage in `.groovy` files — use `.collect`, `.findAll`, `.groupBy`, `.find`, `.any`, `.every`, `.inject`. This is the Grails expression of the team-wide "prefer functional style" rule.
+4. **Language floors.** OpenJDK 8 — no `var`, records, `List.of()`, or text blocks. Groovy 2.4 — no method references (`::`), `!in`, `!instanceof`. Node 14 — no optional chaining in Webpack / build scripts.
+5. **No `@Autowired`.** Use Grails convention-based injection — declare dependencies as `def serviceName`.
+6. **Raw SQL.** Prefer GORM dynamic finders, criteria queries, or HQL. If raw SQL is necessary, comment the reason inline.
+7. **Boy Scout exemption for upstream files.** Do NOT clean up indentation, import order, or naming in upstream files you're editing — every incidental change becomes a future merge conflict. Apply the Boy Scout Rule only inside `org.pih.warehouse.custom.*`, `src/js/custom/*`, and `grails-app/migrations/custom/*`.
+
+## Overrides to Team Conventions
+
+- **Boy Scout Rule is suspended for upstream files.** See Upstream Compatibility rule 8. Apply cleanups only inside `org.pih.warehouse.custom.*`, `src/js/custom/*`, and `grails-app/migrations/custom/*`.
+
+Note on functional style: the team-wide "prefer functional style" rule is **not** an override here — it matches the actual convention in upstream code (Groovy services use `.collect/.findAll/.groupBy/.inject` ~8.7× more often than imperative `for` loops; React components use `.map/.filter/.reduce` ~75× more often). Express the rule via Groovy collection methods in `.groovy` files (Streams are not idiomatic in Groovy 2.4) and via standard array methods in `.js`/`.jsx`.
+
+## Gotchas
+
+- **`.claude/.context/` is per-developer.** Already excluded via `.gitignore:53`. Do not commit anything under it. The rest of `.claude/` is tracked on this EST branch.
+- **Upstream owns top-level `docs/`** (the admin guide). Never add team/fork docs there — use `.claude/docs/` to avoid merge collisions.
+- **`dependecy-review.yml` misspelling** is upstream. Renaming it creates a forever merge conflict. Leave it.
+- **Java 8 + Groovy 2.4 + Node 14** — the stack is frozen by upstream. Resist the urge to modernize syntax in files you touch.
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index edf086ea39b..d459aa5d62b 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -4,6 +4,8 @@ services:
       extends: 
         file: docker-compose-base.yml
         service: app
+      volumes:
+        - ./openboxes-config.properties:/app/.grails/openboxes-config.properties:ro
       depends_on: 
         db:
           condition: service_healthy
@@ -23,6 +25,8 @@ services:
         MYSQL_DATABASE: openboxes
         MYSQL_USER: ${DATASOURCE_USERNAME:-openboxes}
         MYSQL_PASSWORD: ${DATASOURCE_PASSWORD:-openboxes}
+      ports:
+        - "3306:3306"
       volumes:
         - ./mysql/:/var/lib/mysql/
       healthcheck:
diff --git a/docker/openboxes-config.properties b/docker/openboxes-config.properties
new file mode 100644
index 00000000000..de289684f6a
--- /dev/null
+++ b/docker/openboxes-config.properties
@@ -0,0 +1,32 @@
+# =============================================================================
+# OpenBoxes override configuration
+# Mounted into the container at /app/.grails/openboxes-config.properties
+# These values override defaults set in grails-app/conf/application.yml
+# =============================================================================
+
+# Database — overridden by DATASOURCE_* env vars in docker-compose, but kept here as fallback
+# dataSource.url=jdbc:mysql://db/openboxes?useSSL=false
+# dataSource.username=openboxes
+# dataSource.password=openboxes
+
+# Admin email
+# openboxes.admin.email=admin@example.com
+
+# Barcode scanner (disabled by default)
+openboxes.scannerDetection.enabled = false
+
+
+# Identifier formats
+openboxes.identifier.order.format = NNNLLL
+openboxes.identifier.product.format = LLNN
+openboxes.identifier.requisition.format = NNNLLL
+openboxes.identifier.shipment.format = NNNLLL
+openboxes.identifier.transaction.format = AAA-AAA-AAA
+
+# Mail (disabled by default — configure to enable)
+grails.mail.enabled = false
+# grails.mail.host=smtp.example.com
+# grails.mail.port=587
+# grails.mail.username=user@example.com
+# grails.mail.password=secret
+# grails.mail.from=noreply@example.com
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 00000000000..6cbbe24b2df
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,117 @@
+# OpenSpec project configuration
+context:
+  Project: OpenBoxes (EyeSeeTea fork)
+  What it is: |
+    Open-source Logistics Management Information System (LMIS) for healthcare
+    and humanitarian supply chains. This repository is EyeSeeTea's fork, which
+    layers customer-specific customizations on top of upstream PIH OpenBoxes.
+
+  Tech stack:
+    - Language: Groovy 2.4.21, Java 8 (OpenJDK 8), JavaScript (Node 14)
+    - Framework: Grails 3.3.16 on Spring Boot
+    - ORM: GORM / Hibernate 5.2.18
+    - Database: MySQL 8 (MariaDB 10.3 also supported)
+    - Migrations: Liquibase via Grails Database Migration plugin
+    - Frontend: React 16.8 + Redux + Webpack 5
+    - Test runner: JUnit (Gradle) for backend, Jest 29 + React Testing Library for frontend
+    - Build tool: Gradle 5.x (backend), npm 6–7 (frontend)
+    - External APIs: none by default; customer deployments may add CPR feeds, DHIS2, etc.
+    - Deployment: Docker (OpenJDK 8 base), Docker Compose
+
+  Directory structure: |
+    grails-app/
+      controllers/       # thin HTTP layer
+      services/          # business logic (transactional by default)
+      domain/            # GORM domain classes (no JPA annotations)
+      views/             # GSP server-rendered pages
+      migrations/        # Liquibase changesets
+      conf/              # application.yml, application.groovy, resources.groovy
+      i18n/              # message properties (Crowdin-managed)
+      assets/            # asset-pipeline assets
+    src/main/java/       # Java helpers and utilities
+    src/js/              # React frontend (components/, reducers/, api/, …)
+    src/js/custom/       # EST custom frontend (isolate here, not in src/js/)
+    docker/              # docker-compose + dev DB config
+    openspec/            # change proposals and archive (this directory)
+    .claude/             # Claude Code tooling (tracked except .context/)
+
+  Custom code isolation (CRITICAL):
+    - Backend: org.pih.warehouse.custom.<feature>/
+    - Frontend: src/js/custom/<feature>/
+    - Migrations: grails-app/migrations/custom/ (or clearly-prefixed)
+    Every custom file lives under one of these paths so "what's custom?" is a
+    file listing rather than a patch diff against upstream.
+
+  Configuration:
+    - grails-app/conf/application.yml      # Grails config (upstream; prefer external overrides)
+    - grails-app/conf/application.groovy   # Grails config (upstream)
+    - grails-app/conf/spring/resources.groovy  # Spring bean overrides (extension point)
+    - docker/openboxes-config.properties   # dev/container config
+    - External config file path is set per environment; customer config
+      belongs on the customer's release/est/<client>/<version> branch.
+
+  Canonical commands:
+    install: npm install
+    dev: ./gradlew bootRun   # backend; run `npm run watch` alongside for frontend
+    build: ./gradlew assemble && npm run bundle
+    test: ./gradlew test && npm test
+    lint: npm run eslint
+    coverage: ./gradlew jacocoTestReport
+    security: ./gradlew dependencyCheckAnalyze
+
+  Code conventions: |
+    Team-wide conventions from ~/.claude/est/CLAUDE.md apply (Conventional Commits,
+    functional style, test quality, pre-commit self-review, Boy Scout Rule).
+
+    Project-specific adaptations:
+      - Grails conventions: thin controllers, service injection via `def serviceName`,
+        GORM dynamic finders and criteria queries (no JPA annotations, no @Autowired).
+      - Groovy functional style uses .collect/.findAll/.groupBy/.inject/.find/.any/.every
+        instead of Java Streams (Streams are not idiomatic in Groovy 2.4).
+      - Boy Scout Rule is SUSPENDED for upstream files (anything outside
+        org.pih.warehouse.custom.* / src/js/custom/* / grails-app/migrations/custom/*)
+        because incidental edits become merge conflicts on upstream replays.
+      - Language floors: OpenJDK 8, Groovy 2.4, Node 14. Do not use newer syntax.
+      - Upstream-bound commits use `OBPIH-XXXX Description (#PR)` format;
+        EST/customer-branch commits use Conventional Commits.
+
+  Architecture: |
+    Grails MVC layered architecture:
+      Controllers (grails-app/controllers/) → Services (grails-app/services/)
+        → Domain (grails-app/domain/) via GORM
+
+    Frontend is a React SPA under src/js/, bundled by Webpack, served by the
+    same Grails app. Some pages are still server-rendered GSP (grails-app/views/).
+
+    Fork layering (see .claude/docs/FORK_MAINTENANCE.md):
+      release/<version>                    upstream-pristine mirror
+        └─ release/est/<version>           EyeSeeTea shared layer (this branch)
+              ├─ release/est/spocc/<version>     Samaritan's Purse OCC customer layer
+              └─ release/est/<client>/<version>  other customer layers
+
+  Non-goals:
+    - Do NOT reformat, reorder imports, or rename symbols in upstream files.
+    - Do NOT introduce JPA annotations or Spring `@Autowired` — stay Grails-idiomatic.
+    - Do NOT modernize to Java 11+/Groovy 3+/Node 16+ syntax anywhere in the codebase.
+    - Do NOT add top-level docs/ files — that directory is owned by upstream.
+    - Do NOT edit existing upstream Liquibase changesets — always add new ones.
+    - Do NOT commit customer-specific code onto release/est/<version> — push it
+      down to the customer's own release/est/<client>/<version> branch.
+
+  Testing strategy: |
+    Backend:
+      - Unit tests (Spock/JUnit) under src/test/groovy and test/
+      - Integration tests hit a real database via Grails' test harness
+      - Run with ./gradlew test; coverage via ./gradlew jacocoTestReport
+    Frontend:
+      - Jest + React Testing Library under src/js/**/__tests__/ (see jest config
+        in package.json)
+      - Run with npm test
+    Assertions are concrete values, not toBeDefined/toBeTruthy (team-wide rule).
+
+rules:
+  # The team-wide CLAUDE.md and auto-loaded path-scoped rules cover commit style,
+  # functional style, test quality, Boy Scout, etc. This section is for project-specific
+  # rules that deviate from or extend those defaults. See .claude/CLAUDE.md for the
+  # authoritative list of project-specific hard rules (Upstream Compatibility,
+  # Fork Maintenance & Branching, Pre-Commit Self-Review — Project-Specific).
diff --git a/package-lock.json b/package-lock.json
index 564109154c9..9ca9ba65030 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1254,20 +1254,20 @@
       "integrity": "sha512-rLu3wcBWH4P5q1CGoSSH/i9hrXs7SlbRLkoq9IGuoPYNGQvDJ3pt/wmOM+XgYjIDRMVIdkUWt0RsfzF50JfnCw=="
     },
     "@floating-ui/core": {
-      "version": "1.7.3",
-      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.3.tgz",
-      "integrity": "sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==",
+      "version": "1.7.5",
+      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.5.tgz",
+      "integrity": "sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==",
       "requires": {
-        "@floating-ui/utils": "^0.2.10"
+        "@floating-ui/utils": "^0.2.11"
       }
     },
     "@floating-ui/dom": {
-      "version": "1.7.4",
-      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.4.tgz",
-      "integrity": "sha512-OOchDgh4F2CchOX94cRVqhvy7b3AFb+/rQXyswmzmGakRfkMgoWVjfnLWkRirfLEfuD4ysVW16eXzwt3jHIzKA==",
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.6.tgz",
+      "integrity": "sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==",
       "requires": {
-        "@floating-ui/core": "^1.7.3",
-        "@floating-ui/utils": "^0.2.10"
+        "@floating-ui/core": "^1.7.5",
+        "@floating-ui/utils": "^0.2.11"
       }
     },
     "@floating-ui/react": {
@@ -1281,17 +1281,17 @@
       }
     },
     "@floating-ui/react-dom": {
-      "version": "2.1.6",
-      "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.6.tgz",
-      "integrity": "sha512-4JX6rEatQEvlmgU80wZyq9RT96HZJa88q8hp0pBd+LrczeDI4o6uA2M+uvxngVHo4Ihr8uibXxH6+70zhAFrVw==",
+      "version": "2.1.8",
+      "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.8.tgz",
+      "integrity": "sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==",
       "requires": {
-        "@floating-ui/dom": "^1.7.4"
+        "@floating-ui/dom": "^1.7.6"
       }
     },
     "@floating-ui/utils": {
-      "version": "0.2.10",
-      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.10.tgz",
-      "integrity": "sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ=="
+      "version": "0.2.11",
+      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.11.tgz",
+      "integrity": "sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg=="
     },
     "@fontsource/inter": {
       "version": "4.5.15",
@@ -12653,9 +12653,9 @@
       "dev": true
     },
     "tabbable": {
-      "version": "6.3.0",
-      "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.3.0.tgz",
-      "integrity": "sha512-EIHvdY5bPLuWForiR/AN2Bxngzpuwn1is4asboytXtpTgsArc+WmSJKVLlhdh71u7jFcryDqB2A8lQvj78MkyQ=="
+      "version": "6.4.0",
+      "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.4.0.tgz",
+      "integrity": "sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg=="
     },
     "table": {
       "version": "5.4.6",

From 0125f7832b159205ed19ab5fd94c41a1f35190ce Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Thu, 16 Apr 2026 11:23:07 +0800
Subject: [PATCH 2/7] est pr template

---
 .github/pull_request_template.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 450d56ca03b..50380307f73 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,13 +1,15 @@
+### :pushpin: References
+
+-   **Issue:** Closes #<task-id>
+
+### :memo: Implementation
+
 ### :sparkles: Description of Change
 
 [//]: <> (A concise summary of what is being changed. Please provide enough context for reviewers to be able to understand the change and why it is necessary.)
 
-**Link to GitHub issue or Jira ticket:**
-
 **Description:**
 
+### :video_camera: Screenshots/Screen capture
 
----
-### :camera: Screenshots & Recordings (optional)
-
-[//]: <> (If this PR contains a UI change, consider attaching one or more screenshots or recordings to help reviewers visualize the change. Otherwise, you can remove this section.)
+### :fire: Notes to the tester

From cb5ebacc9b94417412237f389f32f36dda8d7b6a Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Thu, 16 Apr 2026 11:55:55 +0800
Subject: [PATCH 3/7] docs(rules): enforce camelCase for custom package folder
 names

Tighten the naming convention from "kebab-case or camelCase" to
camelCase-only for all custom/<feature> paths (backend and frontend).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/rules/custom-package-isolation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/rules/custom-package-isolation.md b/.claude/rules/custom-package-isolation.md
index 0e01d31de25..99f4f2b8833 100644
--- a/.claude/rules/custom-package-isolation.md
+++ b/.claude/rules/custom-package-isolation.md
@@ -40,7 +40,7 @@ paths:
 | Backend unit tests | `src/test/groovy/org/pih/warehouse/custom/<feature>/` |
 | Backend integration tests | `src/integration-test/groovy/org/pih/warehouse/custom/<feature>/` |
 
-**`<feature>` is a short kebab-case or camelCase name** describing the feature: `gs1-barcode`, `ims-migration`, `seasonCartonCascade`, etc. Match the convention already in use within the custom folder.
+**`<feature>` must be a camelCase name** describing the feature: `stockTransferDocuments`, `seasonCartonCascade`, `imsImport`, etc. Do **not** use kebab-case (`gs1-barcode`) or flat lowercase (`stocktransferdocuments`) — camelCase is the enforced convention for all custom package and folder names across both backend and frontend.
 
 ## Why
 

From cc12ed17b87deb187902610b2ba1013ffdcaecf3 Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Thu, 16 Apr 2026 12:06:48 +0800
Subject: [PATCH 4/7] chore(commands): add /propagate-change command for branch
 hierarchy updates

---
 .claude/commands/propagate-change.md | 137 +++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 .claude/commands/propagate-change.md

diff --git a/.claude/commands/propagate-change.md b/.claude/commands/propagate-change.md
new file mode 100644
index 00000000000..7fbdfce894f
--- /dev/null
+++ b/.claude/commands/propagate-change.md
@@ -0,0 +1,137 @@
+---
+description: Make a change on a parent branch and propagate it down through the branch hierarchy (EST → client → feature). Handles git archaeology, level selection, merges, and push confirmation.
+---
+
+# /propagate-change — Propagate a change through the branch hierarchy
+
+You are about to help the user make a change on a parent branch and merge it down through the fork's layered branch model. This is used for rule updates, CLAUDE.md changes, config overrides, docs — anything that should live higher than the current feature branch.
+
+## Step 1: Understand the change
+
+Ask the user (if not already provided via $ARGUMENTS):
+- **What change do you need to make?** (e.g., "add a camelCase naming rule to custom-package-isolation.md")
+- **Which file(s) will be modified or created?**
+
+If the user already described the change in $ARGUMENTS, confirm your understanding before proceeding.
+
+## Step 2: Map the branch hierarchy
+
+Run these commands to discover the branch structure:
+
+```bash
+# Current branch
+git branch --show-current
+
+# All remote EST/client branches
+git branch -r | grep -E 'release/est/'
+
+# Find the merge base between the current branch and each release branch
+# to determine the ancestry chain
+```
+
+Build the hierarchy by tracing merge bases. The typical structure is:
+
+```
+develop (upstream)
+  └─ release/est/<version>           ← EST shared layer
+       └─ release/est/<client>/<version>  ← per-client layer (one or more)
+            └─ feature/* or fix/*         ← current working branch
+```
+
+Present the discovered hierarchy to the user as a tree, including commit hashes so they can verify.
+
+## Step 3: Ask the propagation level
+
+Ask the user:
+
+> **Up to what level should this change be committed?**
+>
+> 1. **EST shared** (`release/est/<version>`) — applies to all clients
+> 2. **Client** (`release/est/<client>/<version>`) — just this client
+> 3. **Current branch only** — no propagation needed
+>
+> The change will be committed at the chosen level and merged down to your current branch.
+
+Wait for their answer before proceeding.
+
+## Step 4: Pre-flight checks
+
+```bash
+# Ensure working tree is clean
+git status --short
+
+# Ensure the target branch is up to date with remote
+git fetch origin
+git log --oneline origin/<target-branch>..<target-branch>  # should be empty
+git log --oneline <target-branch>..origin/<target-branch>  # should be empty
+```
+
+If the working tree is dirty, ask the user to commit or stash first.
+If the target branch is behind remote, fast-forward it first.
+If the target branch is ahead of remote, warn the user and ask how to proceed.
+
+## Step 5: Make the change
+
+1. **Record the current branch** so you can return to it later.
+2. **Checkout the target branch** (the level chosen in Step 3).
+3. **Apply the change** — edit/create the file(s) as described.
+4. **Commit** using conventional commits (`docs(rules):`, `chore(config):`, etc.).
+5. Do NOT push yet.
+
+## Step 6: Merge down through the hierarchy
+
+**Always merge, never cherry-pick.** Cherry-picking creates duplicate commits with different SHAs, which causes merge conflicts when branches merge naturally later. Merging preserves commit lineage so git knows the change is already present on child branches.
+
+For each level, merge the parent into the child:
+
+```bash
+git checkout <next-level-branch>
+git merge <parent-branch> --no-edit
+```
+
+If there are conflicts:
+- Show the conflicts to the user
+- Ask how to resolve them
+- Do NOT force-resolve or skip
+
+Continue until you reach the original working branch.
+
+## Step 7: Verify
+
+```bash
+# Show the full log from the target branch down to current
+git log --oneline --graph <target-branch>..HEAD
+
+# Confirm the change is present
+# (read the modified file to verify)
+```
+
+Show the user the merge chain and the final state of the changed file(s).
+
+## Step 8: Push
+
+Ask the user which branches to push. List each branch that has unpushed commits:
+
+```bash
+git log --oneline origin/<branch>..<branch>
+```
+
+**Never push without explicit user confirmation.** Present the list and wait for approval:
+
+> The following branches have unpushed commits:
+> - `release/est/<version>` — N commit(s)
+> - `release/est/<client>/<version>` — N commit(s)
+> - `feature/<name>` — N commit(s)
+>
+> Which branches should I push? (all / list specific / none)
+
+Push only what the user approves. Never force push.
+
+## Important constraints
+
+- **Always merge, never cherry-pick** — preserves commit lineage and avoids duplicate-commit conflicts.
+- **Never force push** to any branch.
+- **Never amend** commits that are already on remote.
+- **Always use conventional commits** for the change itself.
+- **Always return to the original branch** when done.
+- **If anything goes wrong**, stop and explain — don't try to recover silently.

From 59c7abb80e02873b7d079752a4825f13653caced Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Mon, 27 Apr 2026 10:15:45 +0800
Subject: [PATCH 5/7] docs(rules): add upstream-entity-extension rule and
 gitignore lockfile

Adds a new rule for schema-level upstream isolation (side tables vs
column injection) that complements the existing custom-package-isolation
file rule. Documents the openboxes-domain-model skill in CLAUDE.md.
Ignores .claude/scheduled_tasks.lock runtime artifact.
---
 .claude/rules/custom-package-isolation.md  |  2 +
 .claude/rules/upstream-entity-extension.md | 87 ++++++++++++++++++++++
 .gitignore                                 |  3 +-
 CLAUDE.md                                  |  3 +-
 4 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 .claude/rules/upstream-entity-extension.md

diff --git a/.claude/rules/custom-package-isolation.md b/.claude/rules/custom-package-isolation.md
index 99f4f2b8833..9d12d6c1aef 100644
--- a/.claude/rules/custom-package-isolation.md
+++ b/.claude/rules/custom-package-isolation.md
@@ -48,6 +48,8 @@ OpenBoxes is a **fork** of upstream PIH OpenBoxes. We pull upstream updates peri
 
 **The corollary:** the Boy Scout Rule from the global CLAUDE.md is **suspended** for any file outside the custom folders. Do not reformat, reorder imports, rename symbols, or "clean up" upstream files. Every incidental edit is a future merge conflict for zero functional benefit.
 
+**Schema-level analogue:** this rule is about upstream *files*. The schema version — don't inject columns onto upstream tables or extend upstream domain classes at runtime — lives in `upstream-entity-extension.md`. When you need to add data to an existing upstream entity, create a custom side-table with a UNIQUE FK rather than modifying the upstream schema.
+
 ## When You MUST Touch an Upstream File
 
 Sometimes a feature genuinely requires modifying an existing upstream file (adding a menu link, registering a new controller, hooking into an existing wizard step). The rules are:
diff --git a/.claude/rules/upstream-entity-extension.md b/.claude/rules/upstream-entity-extension.md
new file mode 100644
index 00000000000..42aa145de10
--- /dev/null
+++ b/.claude/rules/upstream-entity-extension.md
@@ -0,0 +1,87 @@
+---
+paths:
+  - "grails-app/domain/**"
+  - "grails-app/migrations/**"
+  - "src/main/groovy/**"
+---
+
+# Upstream Entity Extension — Side Tables, Never Column Injection
+
+> **The rule:** when a custom feature needs to add data to an upstream domain entity (`Shipment`, `Container`, `Product`, `Organization`, `Person`, `Location`, `RequisitionItem`, `ShipmentItem`, etc.), add the data in a **new custom domain class with a UNIQUE FK to the upstream entity** — a 1-to-1 (or 1-to-many) side table. **Never** add columns to upstream tables and never extend upstream domain classes via GORM/metaclass/trait injection.
+
+## Why
+
+The fork isolation contract (see `rules/custom-package-isolation.md`) is about keeping upstream **files** untouched so merges stay clean. This rule extends the same contract to upstream **schemas**:
+
+- **Upstream table schema collisions.** If we add a `seal_number` column to the upstream `container` table and upstream later adds the same column (with different semantics), merge resolution is painful and potentially data-destructive.
+- **Runtime class extension is fragile.** GORM metaclass tricks, AST transforms, or trait-based property additions surprise anyone reading the upstream domain class — the class in the source file does not match the runtime shape. Debugging gets harder.
+- **Side-tables scale cleanly.** Collections (e.g. multiple seals per container) can't be injected onto upstream classes without adding new FK tables anyway — at which point you've built a side-table with worse ergonomics.
+- **Nulls on unused rows.** An injected scalar column forces every upstream row to carry it, even rows the feature never touches. A side table only has rows for entities the feature actually extends.
+
+## The pattern
+
+```groovy
+// grails-app/domain/org/pih/warehouse/custom/<feature>/CustomContainer.groovy
+package org.pih.warehouse.custom.shipmentPackaging
+
+import org.pih.warehouse.shipping.Container  // upstream — read-only reference
+
+class CustomContainer {
+    Container container              // UNIQUE FK to upstream — the side-table "anchor"
+    Boolean isShipperOwned = false   // feature-specific scalar
+    static hasMany = [
+        seals: CustomContainerSeal,
+        customsReferences: CustomContainerCustomsReference,
+    ]
+    static constraints = {
+        container unique: true       // 1-to-1 enforcement
+    }
+    static mapping = {
+        id generator: 'uuid'
+        table 'custom_container'
+    }
+}
+```
+
+Traversal from a line:
+
+```groovy
+// Find the CustomContainer for a ShipmentItem's container (one extra query)
+CustomContainer cc = shipmentItem.container ? CustomContainer.findByContainer(shipmentItem.container) : null
+```
+
+Or, if you want native GORM navigation, add a **one-direction** `hasOne` back-reference *on the custom side only* — do **not** add a property to upstream `Container`:
+
+```groovy
+class CustomContainer {
+    static belongsTo = [container: Container]  // still cascades lifecycle correctly
+    // ...
+}
+```
+
+Still zero edits to upstream `Container.groovy`.
+
+## Explicitly forbidden
+
+| Anti-pattern | Why it fails the rule |
+|---|---|
+| `Container.metaClass.sealNumber = null` and friends | Runtime metaclass mutation — fragile, invisible in source. |
+| Adding a Liquibase migration that does `addColumn(tableName: 'container', ...)` | Modifies the upstream schema directly. Merge risk if upstream adds a same-named column later. |
+| Groovy trait applied to upstream domain class via AST | Changes the upstream class's bytecode shape at runtime. |
+| Subclassing upstream domain class (`class CustomContainer extends Container`) | Creates an STI/table-per-hierarchy coupling that changes the upstream table's semantics. |
+
+## When the rule does NOT apply
+
+- **Seed data** for upstream lookup tables (`ContainerType`, `LocationType`, `DocumentType`, `ReferenceNumberType`, etc.). Adding rows is not schema change. Use a Liquibase changeset under `grails-app/migrations/custom/` and make it idempotent (preconditions).
+- **Config / feature flags** — belong in external config, not in domain extensions.
+- **Transient computed properties** you need in a service layer — write a helper service or Groovy category; don't persist anything.
+
+## Related rules
+
+- `rules/custom-package-isolation.md` — upstream **files** stay pristine; this rule is the schema-level analogue.
+- `rules/groovy/patterns.md` — GORM constraints/mappings/query conventions that apply to the new side-table classes themselves.
+- `rules/ims-custom-domain.md` — IMS-specific side tables (`CustomContainer`, `CustomRequisitionItem`, `CustomShipmentItem`, `CustomShipmentMilestone`, `CustomOrganizationContact`, `Sli`, `DistributionPlan`) all follow this pattern.
+
+## Quick self-check before writing a migration
+
+If your custom Liquibase changeset contains `addColumn(tableName: '<upstream-table>', ...)`, stop. Replace it with `createTable(tableName: 'custom_<feature>', ...)` that has a `FOREIGN KEY ... REFERENCES <upstream-table>(id)` and a `UNIQUE` constraint on that FK column (for 1-to-1) or an index (for 1-to-many).
diff --git a/.gitignore b/.gitignore
index b997ca6b7e1..a646de98b18 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,4 +50,5 @@ docker/openboxes.war
 .gradle
 .~*#
 
-.claude/.context/
\ No newline at end of file
+.claude/.context/
+.claude/scheduled_tasks.lock
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 30d411ee92a..d89c0549a31 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -121,7 +121,7 @@ npm test                # Frontend
 - `react-reviewer` — Reviews React 16.8 / Redux / JSX changes under `src/js/**`. Enforces custom-package isolation, form-library consistency, and i18n.
 
 ### Skills (`.claude/skills/`)
-- **Project-specific**: `code-review` (Grails layer paths + OpenBoxes gotchas)
+- **Project-specific**: `code-review` (Grails layer paths + OpenBoxes gotchas), `openboxes-domain-model` (entity/service map)
 - **Supply Chain Domain**: `customs-trade-compliance`, `inventory-demand-planning`, `logistics-exception-management`, `returns-reverse-logistics`, `production-scheduling`, `quality-nonconformance`
 
 > **Intentionally excluded** (incompatible with this stack): `springboot-patterns`, `springboot-security`, `springboot-tdd`, `springboot-verification`, `jpa-patterns`, `java-coding-standards`. Those teach Spring Boot + JPA + Java 17+ patterns that contradict Grails / GORM / Java 8. Do **not** reintroduce them from upstream skill libraries.
@@ -131,6 +131,7 @@ npm test                # Frontend
 Auto-loaded via `paths:` frontmatter — Claude sees them whenever it touches matching files.
 
 - `custom-package-isolation.md` — **(CRITICAL)** all new code goes under `custom/` folders for upstream-merge safety. Auto-loads on `grails-app/**`, `src/main/**`, `src/main/groovy/**`, `src/main/java/**`, `src/main/webapp/**`, `src/test/**`, `src/integration-test/**`, `src/js/**`, `test/**`.
+- `upstream-entity-extension.md` — **(CRITICAL)** schema-level analogue of custom-package-isolation. Extend upstream domains via a side-table with a UNIQUE FK — **never** inject columns onto upstream tables or mutate upstream classes via metaclass / AST / subclassing. Auto-loads on `grails-app/domain/**`, `grails-app/migrations/**`, `src/main/groovy/**`.
 - `groovy/patterns.md` — Grails conventions, GORM query decision tree, transactional-by-default footgun, constraints/mappings, Liquibase DSL, functional Groovy idioms. Applies to `grails-app/**/*.groovy`, `src/main/groovy/**`.
 - `groovy/testing.md` — Spock + Grails test mixins, integration tests, data-driven tables. Applies to `src/test/groovy/**`, `src/integration-test/groovy/**`, `test/**/*.groovy`.
 - `java/patterns.md` / `java/coding-style.md` / `java/security.md` — for `src/main/java/**` helpers only. Java 8 floor, no JPA, no Spring stereotypes on new beans.

From 61f95dc3044dca9461ff7876c35c53d6230f9b2d Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Wed, 29 Apr 2026 12:24:54 +0800
Subject: [PATCH 6/7] docs(rules): expand liquibase guidance in
 custom-package-isolation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the load-bearing details for safely landing custom Liquibase
migrations on the EST fork:

- Placement: include line goes after the upstream release loop and
  before the views rebuild so upstream migrations apply first, ours
  second, and view rebuilds last.
- Aggregator clarification: adding includes inside custom/changelog.groovy
  is never an upstream touch.
- FK ordering: include order in custom/changelog.groovy must put FK-target
  files above FK-holder files; rollback runs in reverse-application order.
- Mandatory rollback {} block on every changeset.
- Liquibase id-collision protection via (id, author, filename) tuple —
  use author 'eyeseetea' and the custom/ folder for namespace isolation.
---
 .claude/rules/custom-package-isolation.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/.claude/rules/custom-package-isolation.md b/.claude/rules/custom-package-isolation.md
index 9d12d6c1aef..6dac8f3fa16 100644
--- a/.claude/rules/custom-package-isolation.md
+++ b/.claude/rules/custom-package-isolation.md
@@ -94,10 +94,19 @@ Add the custom changeset to the master changelog **via an include line**, not by
 // grails-app/migrations/changelog.groovy
 databaseChangeLog = {
     // ... upstream includes unchanged ...
+    for (TaggedMigrationVersion release : currentAndNewerReleases) {
+        include(file: release.toString() + "/changelog.xml")
+    }
+
     include file: 'custom/changelog.groovy'  // <-- add this ONE line
+                                             //     after the release loop, before views rebuild
+
+    include(file: 'views/changelog.xml')
 }
 ```
 
+**Placement matters.** Put the include line **after the upstream release loop** and **before the views rebuild**. That way upstream migrations apply first, ours second, and view rebuilds last (so any custom views are not dropped by the rebuild step). The release loop is the long-running part of upstream's bootstrap; everything custom rides after it.
+
 Then `grails-app/migrations/custom/changelog.groovy` aggregates all custom migrations:
 
 ```groovy
@@ -107,7 +116,13 @@ databaseChangeLog = {
 }
 ```
 
-This minimizes upstream-file touches to one line.
+This minimizes upstream-file touches to one line. **Adding new include lines to `custom/changelog.groovy` is never an upstream touch** — that file is ours.
+
+**Order changesets by FK dependency.** When one custom feature's tables reference another custom feature's tables (e.g. an approval-tier FK into a location-level table), the include order in `custom/changelog.groovy` must put the FK-target file **above** the FK-holder file. Date-prefixed filenames usually sort correctly; if same-day shipments collide, reorder the include lines explicitly. Rollback runs in reverse-application order automatically — get the apply order right and rollback follows.
+
+**Every changeset MUST have an explicit `rollback {}` block.** Don't rely on Liquibase's auto-derive (it doesn't always work for tables with FKs). For `createTable` use `rollback { dropTable(tableName: '...') }`; for `insert` use `rollback { delete(tableName: '...', where: "...") }`. Drop FK-holding tables before FK-target tables — the per-changeset rollback runs in reverse-application order, so getting the apply order right gives you the correct rollback order for free.
+
+**Liquibase id collisions are protected by namespace, not by id uniqueness.** Liquibase tracks changesets by `(id, author, filename)`. Use `author = 'eyeseetea'` and put files under `custom/` so even if upstream coincidentally ships an id matching one of ours, the tuple differs and the rows are independent in `databasechangelog`. Date-prefix changeset ids (`2026-04-13-01-...`) for human readability — collisions inside our own folder are the only ones we have to avoid manually.
 
 ### Spring beans
 

From ceca011a6b9dfe5e3bdbeebe6bf4b453c55d0147 Mon Sep 17 00:00:00 2001
From: gqcorneby <185756521+gqcorneby@users.noreply.github.com>
Date: Wed, 29 Apr 2026 12:33:10 +0800
Subject: [PATCH 7/7] chore(migrations): pre-wire custom liquibase aggregator
 on EST
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the one-time upstream-file touch to grails-app/migrations/changelog.groovy
so every client and feature branch inherits the custom-migration entrypoint.
New custom migrations now only need to:
  1. Drop a file under grails-app/migrations/custom/<date>-<feature>.groovy
  2. Append a one-line include to custom/changelog.groovy (which is ours)

No more per-feature edits to the upstream master changelog. The aggregator
ships empty — Liquibase loads the empty databaseChangeLog block as a no-op
until real changesets are added.

Updated .claude/rules/custom-package-isolation.md to reflect that the
wiring is pre-installed; the rule no longer asks future authors to edit
the upstream master changelog.
---
 .claude/rules/custom-package-isolation.md     | 18 ++++++++++--------
 grails-app/migrations/changelog.groovy        |  4 ++++
 grails-app/migrations/custom/changelog.groovy | 16 ++++++++++++++++
 3 files changed, 30 insertions(+), 8 deletions(-)
 create mode 100644 grails-app/migrations/custom/changelog.groovy

diff --git a/.claude/rules/custom-package-isolation.md b/.claude/rules/custom-package-isolation.md
index 6dac8f3fa16..efe084a7476 100644
--- a/.claude/rules/custom-package-isolation.md
+++ b/.claude/rules/custom-package-isolation.md
@@ -88,26 +88,30 @@ Sometimes a feature genuinely requires modifying an existing upstream file (addi
 
 ### Liquibase
 
-Add the custom changeset to the master changelog **via an include line**, not by inlining:
+**The wiring is already in place on EST** — `grails-app/migrations/changelog.groovy` already contains the include line (after the release loop, before the views rebuild), and `grails-app/migrations/custom/changelog.groovy` exists as the aggregator. **You should not edit the upstream master changelog at all.** New custom migrations only need to:
+
+1. Drop a file under `grails-app/migrations/custom/<yyyy-mm-dd>-<feature>.groovy`.
+2. Append a one-line `include file: '<yyyy-mm-dd>-<feature>.groovy'` to `grails-app/migrations/custom/changelog.groovy`.
+
+For reference, the master changelog looks like this — **don't change it**:
 
 ```groovy
-// grails-app/migrations/changelog.groovy
+// grails-app/migrations/changelog.groovy  (upstream — pre-wired, do not edit)
 databaseChangeLog = {
     // ... upstream includes unchanged ...
     for (TaggedMigrationVersion release : currentAndNewerReleases) {
         include(file: release.toString() + "/changelog.xml")
     }
 
-    include file: 'custom/changelog.groovy'  // <-- add this ONE line
-                                             //     after the release loop, before views rebuild
+    include file: 'custom/changelog.groovy'   // <-- already here
 
     include(file: 'views/changelog.xml')
 }
 ```
 
-**Placement matters.** Put the include line **after the upstream release loop** and **before the views rebuild**. That way upstream migrations apply first, ours second, and view rebuilds last (so any custom views are not dropped by the rebuild step). The release loop is the long-running part of upstream's bootstrap; everything custom rides after it.
+**Why placement matters (already correct on EST):** the include sits **after the upstream release loop** and **before the views rebuild** so upstream migrations apply first, ours second, and view rebuilds last (so any custom views aren't dropped by the rebuild step).
 
-Then `grails-app/migrations/custom/changelog.groovy` aggregates all custom migrations:
+The aggregator at `grails-app/migrations/custom/changelog.groovy` is **ours** — appending include lines to it is **never** an upstream touch:
 
 ```groovy
 databaseChangeLog = {
@@ -116,8 +120,6 @@ databaseChangeLog = {
 }
 ```
 
-This minimizes upstream-file touches to one line. **Adding new include lines to `custom/changelog.groovy` is never an upstream touch** — that file is ours.
-
 **Order changesets by FK dependency.** When one custom feature's tables reference another custom feature's tables (e.g. an approval-tier FK into a location-level table), the include order in `custom/changelog.groovy` must put the FK-target file **above** the FK-holder file. Date-prefixed filenames usually sort correctly; if same-day shipments collide, reorder the include lines explicitly. Rollback runs in reverse-application order automatically — get the apply order right and rollback follows.
 
 **Every changeset MUST have an explicit `rollback {}` block.** Don't rely on Liquibase's auto-derive (it doesn't always work for tables with FKs). For `createTable` use `rollback { dropTable(tableName: '...') }`; for `insert` use `rollback { delete(tableName: '...', where: "...") }`. Drop FK-holding tables before FK-target tables — the per-changeset rollback runs in reverse-application order, so getting the apply order right gives you the correct rollback order for free.
diff --git a/grails-app/migrations/changelog.groovy b/grails-app/migrations/changelog.groovy
index 14572faf991..90eda97213a 100644
--- a/grails-app/migrations/changelog.groovy
+++ b/grails-app/migrations/changelog.groovy
@@ -59,6 +59,10 @@ databaseChangeLog = {
         include(file: release.toString() + "/changelog.xml")
     }
 
+    // Custom migrations (EST fork). Aggregated by grails-app/migrations/custom/changelog.groovy.
+    // See .claude/rules/custom-package-isolation.md.
+    include file: 'custom/changelog.groovy'
+
     // Rebuild all views
     include(file: 'views/changelog.xml')
 }
diff --git a/grails-app/migrations/custom/changelog.groovy b/grails-app/migrations/custom/changelog.groovy
new file mode 100644
index 00000000000..9fc44bae2e8
--- /dev/null
+++ b/grails-app/migrations/custom/changelog.groovy
@@ -0,0 +1,16 @@
+/**
+ * Aggregator for custom Liquibase changesets in the EST fork.
+ *
+ * Wired into the master changelog.groovy via a single include line (after the
+ * upstream release loop, before the views rebuild). New custom migrations:
+ *
+ *   1. Drop a file under grails-app/migrations/custom/<yyyy-mm-dd>-<feature>.groovy
+ *      with a `databaseChangeLog = { changeSet(...) { ... rollback { ... } } }` block.
+ *   2. Append a one-line `include file: '<yyyy-mm-dd>-<feature>.groovy'` below.
+ *
+ * Order include lines by FK dependency (target tables above holder tables).
+ * See .claude/rules/custom-package-isolation.md for the full rules.
+ */
+databaseChangeLog = {
+    // No custom migrations yet — append `include file:` lines here as they ship.
+}