Merge branch 'main' into dante01yoon/fe-1584-credits-follow-billing-rail

Author: dante01yoon

.agents/setup

@@ -6,6 +6,24 @@ cd "$repo_root"
 
 if [[ "${AMP_ORB:-}" == 1 ]]; then
   gh auth setup-git
+
+  if ! command -v docker >/dev/null 2>&1 ||
+    ! command -v dockerd >/dev/null 2>&1; then
+    echo "Installing Docker"
+    sudo install -m 0755 -d /etc/apt/keyrings
+    sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
+      -o /etc/apt/keyrings/docker.asc
+    sudo chmod a+r /etc/apt/keyrings/docker.asc
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |
+      sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
+    sudo apt-get update
+    sudo apt-get install -y \
+      docker-ce \
+      docker-ce-cli \
+      containerd.io \
+      docker-buildx-plugin \
+      docker-compose-plugin
+  fi
 fi
 
 node_major="$(tr -d '[:space:]' < "$repo_root/.nvmrc")"

.agents/skills/consolidating-test-setup/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: consolidating-test-setup
+description: Consolidates repeated test setup and teardown into the narrowest shared lifecycle owner. Use when test files repeat initialization, cleanup, environment management, fixtures, or equivalent test doubles.
+---
+
+# Consolidating test setup
+
+Move repeated test plumbing to the narrowest shared owner that can provide it
+reliably. Keep test files focused on behavior.
+
+## Principles
+
+### Prove the code is equivalent
+
+Repetition is evidence, not proof. Similar code may use different defaults,
+ordering, or lifetimes. Group candidates by behavior before treating them as
+duplicates.
+
+### Centralize invariants, not scenarios
+
+Shared setup should establish conditions that hold for every test in its scope.
+State that explains one scenario belongs with that scenario.
+
+### Use the narrowest owner
+
+Prefer the mechanism that already owns the lifecycle. Use runner configuration
+before hooks, scoped fixtures before global setup, and local setup for local
+requirements. Wider reuse is not better reuse.
+
+### Treat setup and teardown as one contract
+
+Define who creates state, how long it lives, and who releases it. Cleanup must
+finish even when a test fails. Tests must not depend on execution order or on
+another test's cleanup.
+
+A shared default should be deterministic and easy to override. Local exceptions
+must not weaken isolation elsewhere.
+
+### Subtract before abstracting
+
+Remove suspected cargo-cult setup and run the affected tests. A targeted pass
+only marks it provisionally unnecessary. Delete it after the complete relevant
+suite and runner-specific lifecycle checks pass. If a test fails, use the
+failure to identify the contract before designing shared setup.
+
+A helper must own a policy or lifecycle, or remove meaningful reader effort.
+Moving the same lines behind a new name is not an improvement.
+
+### Preserve test intent
+
+Do not hide state that matters to the behavior under test. Check history before
+removing synchronization or cleanup because it may guard a past regression.
+Preserve that guarantee even if the implementation changes.
+
+## Runner-specific guidance
+
+Load only the reference for the runner in use:
+
+- [`reference/vitest.md`](reference/vitest.md) for Vitest and similar
+  in-process unit-test runners
+- [`reference/playwright.md`](reference/playwright.md) for Playwright and
+  similar browser-test runners
+
+These references supplement the repository's testing guide. They do not replace
+it. Load both only when the task spans both runners.
+
+## Workflow
+
+### 1. Discover
+
+Read the runner configuration, setup files, fixtures, helpers, and test guidance.
+Count repeated lifecycle behavior and note the suites that use it.
+
+### 2. Classify
+
+For each candidate, record:
+
+- the state it owns
+- its lifetime and scope
+- whether it is an invariant or scenario detail
+- intentional differences between suites
+- behavior already supplied by the runner
+
+### 3. Challenge
+
+Remove the candidate and run every affected suite. Classify it as unnecessary,
+universal, common with exceptions, or suite-specific.
+
+Subagents may evaluate disjoint groups of suites. Require evidence and exception
+reports from each. Keep the design and integration decision in the parent task.
+
+### 4. Place
+
+Choose the required lifetime and scope first. Then use the simplest owner at
+that exact boundary:
+
+- native runner behavior that supports the required scope
+- existing shared setup, fixture, or hook
+- a focused helper or test double
+- the individual suite
+
+Do not move state to a broader owner because its mechanism appears earlier in
+the list.
+
+### 5. Migrate
+
+Move one responsibility at a time. Add the shared owner, then remove only the
+local code it replaces. Keep intentional exceptions and scenario setup visible.
+Avoid unrelated test rewrites.
+
+### 6. Prove
+
+Run affected tests, tests of the shared lifecycle, repository static checks, and
+the complete relevant suite. Measure before and after when the new behavior runs
+for every test. Use enough comparable samples to separate a real change from
+normal variance.
+
+## Report
+
+State the repeated contract, its new owner, retained exceptions, rejected
+alternatives, duplication removed, and validation results. Include performance
+evidence when shared setup could affect suite runtime.
+
+## Guardrails
+
+- Do not replace native runner behavior with a custom abstraction.
+- Do not widen setup scope without evidence.
+- Do not add a helper merely to move code.
+- Do not hide global mutable state behind helper indirection.
+- Do not trade visible test intent for shorter files.
+- Do not trust targeted tests alone after changing shared lifecycle behavior.

.agents/skills/consolidating-test-setup/reference/playwright.md

@@ -0,0 +1,88 @@
+# Playwright setup consolidation
+
+Use this reference for Playwright and similar browser-test runners.
+
+## Read first
+
+Read the Playwright configuration, global setup and teardown, affected fixtures,
+and canonical browser-test guidance. In this repository, inspect:
+
+- `playwright.config.ts`
+- `browser_tests/globalSetup.ts` and `browser_tests/globalTeardown.ts`
+- the fixtures used by the affected specs
+- `docs/guidance/playwright.md`
+- `.agents/checks/playwright-e2e.md`
+- `browser_tests/README.md`
+
+Read fixture code directly. Do not guess its setup order or cleanup guarantees.
+
+## Map the lifetime
+
+Browser tests span the run, worker, browser context, page, application session,
+and external services. Put state at the narrowest boundary that matches its real
+lifetime.
+
+Reserve run-wide hooks for run-wide resources. Worker fixtures must own isolated
+worker resources. Keep mutable test state test-scoped unless broader ownership
+is proven safe under parallel execution.
+
+## Give fixtures full ownership
+
+Use composable fixtures for resources that need setup and teardown. The fixture
+that creates or mutates a resource must restore or release it after the handoff,
+including when the test fails.
+
+Keep roles separate:
+
+- fixtures own lifecycle and resources
+- page objects own locators and interactions for one UI area
+- helpers coordinate domain actions
+- data fixtures contain data, not runner behavior
+
+Compose fixtures instead of growing a central page object or adding unrelated
+global hooks.
+
+## Preserve ordering
+
+Install configuration, request interception, identity, and initial state before
+the navigation that consumes them. Resolving a high-level fixture may navigate
+before a hook body runs. Read the dependency graph and use fixture options or a
+lower-level dependency for pre-navigation setup.
+
+Do not boot the application and then repair state that should have existed at
+startup.
+
+## Account for external state
+
+Assume parallel execution and fresh workers on retry. Resource identities must
+not collide. Cleanup must affect only resources owned by that test or worker.
+
+Resetting a page or context does not clean backend state or other external
+resources. Define the complete boundary. Use opt-in cleanup when a universal
+reset would erase persistence that a test needs to verify.
+
+Retries expose pollution and readiness problems; they do not solve them.
+
+## Preserve readiness guarantees
+
+A fixture should hand control to the test only after observable readiness. Do
+not centralize arbitrary delays or timing assumptions that belong to one suite.
+
+Check history before removing waits, resets, or teardown. Preserve any race or
+regression guarantee.
+
+## Migrate and prove
+
+For one lifecycle responsibility at a time:
+
+1. Map fixture dependencies and external resources.
+2. Identify setup required before navigation.
+3. Test whether repeated local setup is necessary.
+4. Choose test, worker, or run scope from the resource lifetime.
+5. Put guaranteed cleanup in the owning fixture.
+6. Keep opt-outs for tests that depend on retained state.
+
+Run affected specs first. Repeat them and exercise parallel execution when
+pollution or timing is plausible. Verify failure cleanup for external resources.
+Then run the complete relevant browser suite and static checks. Inspect flaky or
+retried outcomes instead of relying on the final green status.

.agents/skills/consolidating-test-setup/reference/vitest.md

@@ -0,0 +1,77 @@
+# Vitest setup consolidation
+
+Use this reference for Vitest and similar in-process unit-test runners.
+
+## Read first
+
+Read the active Vitest configuration, its full `setupFiles` chain, package-level
+overrides, and the repository's unit-test guidance. In this repository, inspect:
+
+- `vite.config.mts`
+- `vitest.setup.ts` and `vitest.timer.setup.ts`
+- package-level Vitest configuration and setup
+- `docs/guidance/vitest.md`
+- `docs/testing/vitest-patterns.md`
+
+Check behavior against the installed Vitest version. Defaults change, and setup
+files compose.
+
+## Place the responsibility
+
+Use native configuration for lifecycle behavior Vitest already supports. Use a
+setup file only for invariants configuration cannot express. Keep package-only
+behavior out of repository-wide setup.
+
+Separate runner-managed resets, fresh mutable state, process-wide modes that
+need restoration, and scenario state that must remain local. Add hooks only for
+the part of the contract Vitest does not already own.
+
+A global default must fit every test in scope. Find the common behavior from the
+tests, then preserve deliberate opt-outs. When choosing a deterministic
+baseline, keep absolute values local when the value itself is under test.
+
+## Handle mocks carefully
+
+Runner-level reset and restoration can change module-scope test doubles. Check
+whether their default implementations survive and whether tests reprogram them
+during a scenario.
+
+Share a module mock only when it reduces reader effort and preserves behavior.
+Keep assertion handles explicit. Test module re-evaluation because it can replace
+shared mock state while a test still holds the old identity.
+
+Keep test-specific `vi.mock` calls in the test module. A call inside an imported
+helper is not hoisted ahead of that test module's static imports. For shared
+implementations, use `__mocks__` with a local `vi.mock`. For runtime selection,
+call `vi.doMock` before a subsequent dynamic import.
+
+Check whether a setup file imports the mock target, directly or transitively.
+Vitest cannot replace that cached module. Prefer removing the setup import. If it
+is unavoidable, call `vi.resetModules()` inside `vi.hoisted` before the test
+imports the target, and account for setup and test code holding different module
+instances.
+
+Skip the extraction if typed shared code is no simpler than the local mocks or
+needs global mutable indirection.
+
+## Migrate
+
+Work on one lifecycle responsibility at a time:
+
+1. Count and classify local occurrences.
+2. Remove them without adding a replacement.
+3. Use failures to find the contract and exceptions.
+4. Prefer configuration, then the narrowest setup file.
+5. Remove only calls the new owner makes redundant.
+6. Keep mid-test resets and scenario state local.
+
+Subagents may check independent suites, but each must report observed necessity
+and exceptions.
+
+## Prove
+
+Run affected files, setup-contract tests, static checks, and the complete unit
+suite. Shared process state can fail only when unrelated suites run together.
+
+Profile changes that execute for every test. Compare several equivalent runs and
+report variance instead of treating normal noise as a result.