Add Unity SDK architecture + coding agent guardrails

.github/copilot-instructions.md

@@ -0,0 +1,15 @@
+# Copilot / Coding Agent instructions (LootLocker Unity SDK)
+
+Follow these rules for any work in this repo:
+
+## Non-negotiables
+- Never commit directly to `dev` or `main`.
+- PRs must target `dev`.
+- Do not tag/publish/create releases.
+- Do not bump versions or edit release metadata (for example `package.json` version) unless explicitly asked.
+- Keep diffs minimal; do not move/rename files unless explicitly requested.
+- Search first to avoid duplicating helpers/utilities.
+
+## Architecture references
+- Repo structure + “where do I implement X?”: `.github/instructions/architecture.md`
+- Guardrails (agent operating rules): `.github/instructions/guardrails.md`

.github/instructions/architecture.md

@@ -0,0 +1,118 @@
+# Unity SDK architecture & repo structure
+
+- Repo layout: **UPM package at repository root** (customers receive an `Assets/` wrapper via CI packaging).
+- Public entrypoint: `Runtime/Game/LootLockerSDKManager.cs`
+
+For agent operating rules, see: `.github/agent-docs/guardrails.md`.
+
+## Repository map (root)
+- `Runtime/` — Shippable SDK code (runtime + editor-guarded pieces). Main entrypoint is in `Runtime/Game/`.
+- `Tests/` — Unity Test Runner tests and test utilities.
+- `Samples~/` — UPM samples (example scenes/scripts).
+- `Prefabs/` — Exported `.unitypackage` artifacts (not runtime code).
+- `.github/` — Internal repo automation + agent docs (excluded from customer packaging).
+- `docs/` — Internal developer documentation (excluded from customer packaging).
+- `package.json` — UPM package manifest (do not bump version unless explicitly tasked).
+
+## Where the code lives
+
+### Public API surface
+- `Runtime/Game/LootLockerSDKManager.cs`
+  - The user-facing SDK class. Most SDK features are exposed as static methods here.
+  - The class is `partial` and very large; changes here are inherently API-surface changes.
+
+### Runtime “core” services / transport
+- `Runtime/Client/LootLockerHTTPClient.cs` — HTTP transport built on `UnityEngine.Networking.UnityWebRequest`.
+- `Runtime/Client/LootLockerHttpRequestData.cs` — Request data model/formatting used by the HTTP client.
+- `Runtime/Client/LootLockerHTTPExecutionQueueItem.cs` — Execution/queue bookkeeping for HTTP requests.
+- `Runtime/Client/LootLockerRateLimiter.cs` — Client-side rate limiting.
+- `Runtime/Client/LootLockerEndPoints.cs` + `Runtime/Client/EndPointClass.cs` — Endpoint path/method definitions.
+
+### Requests + response models
+- `Runtime/Game/Requests/` — Feature-focused request code.
+  - Convention observed in this repo: many request files also define their **response DTOs** in the same file (e.g., classes deriving from `LootLockerResponse`).
+
+Shared response base + errors:
+- `Runtime/Client/LootLockerResponse.cs` — Base response type + deserialization helper.
+- `Runtime/Client/LootLockerErrorData.cs` — Error payload shape.
+- `Runtime/Client/LootLockerRequestContext.cs` — Context attached to responses.
+
+### Serialization
+- `Runtime/Client/LootLockerJson.cs` — Serialization wrapper.
+  - Uses Newtonsoft JSON when `LOOTLOCKER_USE_NEWTONSOFTJSON` is defined.
+  - Otherwise uses `Runtime/Libraries/ZeroDepJson/`.
+- `Runtime/Libraries/ZeroDepJson/` — Built-in JSON implementation (no external dependency).
+
+### Session / player state (auth tokens, persistence)
+- `Runtime/Client/LootLockerPlayerData.cs` — In-memory player/session token fields.
+- `Runtime/Client/LootLockerStateData.cs` — Service that persists player state and reacts to session lifecycle events.
+- `Runtime/Client/LootLockerStateWriter.cs` — `ILootLockerStateWriter` abstraction; default uses `PlayerPrefs` unless disabled.
+
+### Lifecycle + events
+- `Runtime/Client/ILootLockerService.cs` — Service interface.
+- `Runtime/Client/LootLockerLifecycleManager.cs` — Central manager that instantiates services and coordinates Unity lifecycle.
+- `Runtime/Client/LootLockerEventSystem.cs` — Eventing used by services (e.g., session started/refreshed/ended).
+
+### Configuration
+- `Runtime/Game/Resources/LootLockerConfig.cs` — ScriptableObject settings.
+  - Uses `Resources.Load` at runtime.
+  - Editor-only asset creation/editor integrations are guarded by `#if UNITY_EDITOR`.
+
+### Logging / utilities
+- `Runtime/Game/LootLockerLogger.cs` — SDK logging.
+- `Runtime/Game/LootLockerObfuscator.cs` — Sensitive log obfuscation.
+- `Runtime/Game/Utilities/` — General helpers used by the SDK.
+
+### Editor tooling (repo’s “Editor” area)
+- `Runtime/Editor/` — Editor-only tooling (LootLocker extension UI, log viewer, editor data, etc.).
+  - This is the effective “Editor/” boundary in this repo.
+
+### Tests
+- `Tests/LootLockerTests/PlayMode/` — PlayMode tests + `PlayModeTests.asmdef`.
+- `Tests/LootLockerTestUtils/` — Shared test configuration helpers + `LootLockerTestUtils.asmdef`.
+
+### Samples
+- `Samples~/LootLockerExamples/` — UPM samples + `LootLockerExamples.asmdef`.
+
+## Architectural boundaries / invariants (observed)
+
+### Runtime must be build-safe
+- Any `UnityEditor` usage is expected to be behind `#if UNITY_EDITOR` guards.
+- Editor-only implementations should live under `Runtime/Editor/`.
+
+### Public API discipline
+- Adding/changing public methods in `LootLockerSDKManager` changes the customer-facing surface area.
+- Prefer keeping helper types/methods `internal`/`private` unless they are intentionally part of the public SDK.
+
+### Search-first to avoid duplication
+- Requests, response DTOs, and shared helpers are frequently co-located (especially under `Runtime/Game/Requests/`).
+- Before introducing new utilities or DTOs, search for existing equivalents.
+
+## Where do I implement X?
+
+| Change you want to make | Put it here (real paths in this repo) |
+|---|---|
+| Add/modify a customer-facing SDK method or its documentation | `Runtime/Game/LootLockerSDKManager.cs` |
+| Add a new feature request (API call) | `Runtime/Game/Requests/<Feature>*.cs` contains the DTO structs and their documentation and customer exposure is added through `Runtime/Game/LootLockerSDKManager.cs` and the necessary endpoint constants are added in `Runtime/Client/LootLockerEndPoints.cs` |
+| Add/adjust response DTO fields for a request | Usually in the same `Runtime/Game/Requests/<Feature>*.cs` file (classes deriving `LootLockerResponse`) |
+| Add/adjust endpoint URL/method constants | `Runtime/Client/LootLockerEndPoints.cs` and/or `Runtime/Client/EndPointClass.cs` |
+| Change HTTP behavior (retries, headers, request creation) | `Runtime/Client/LootLockerHTTPClient.cs` + `Runtime/Client/LootLockerHttpRequestData.cs` |
+| Change serialization rules | `Runtime/Client/LootLockerJson.cs` (and `Runtime/Libraries/ZeroDepJson/` if not using Newtonsoft) |
+| Change session/persistence behavior | `Runtime/Client/LootLockerStateData.cs`, `Runtime/Client/LootLockerStateWriter.cs`, `Runtime/Client/LootLockerPlayerData.cs` |
+| Add/adjust config settings | `Runtime/Game/Resources/LootLockerConfig.cs` |
+| Add editor window/extension UI | `Runtime/Editor/` |
+| Add/adjust tests | `Tests/LootLockerTests/PlayMode/` (tests) and `Tests/LootLockerTestUtils/` (shared config) |
+| Add/adjust samples | `Samples~/LootLockerExamples/` |
+
+## Common pitfalls
+- Duplication: search under `Runtime/Game/Requests/` and `Runtime/Client/` before adding new helpers.
+- Accidental API surface growth: avoid adding new `public` types/methods unless that is the goal.
+- Drive-by refactors: keep PRs narrow; large reshuffles make review harder and increase risk.
+- Editor leakage: keep `UnityEditor` references guarded and editor-only code inside `Runtime/Editor/`.
+
+## Links
+- Coding Agent guardrails: `.github/agent-docs/guardrails.md`
+
+## Future expansion (placeholders)
+- Build & test (to be filled by later tasks)
+- CI packaging notes (to be filled by later tasks)

.github/instructions/guardrails.md

@@ -0,0 +1,30 @@
+# Coding Agent Guardrails (LootLocker Unity SDK)
+
+These rules exist to keep changes safe, reviewable, and aligned with how this repo ships.
+
+## Branching + PRs
+- Never commit directly to `dev` or `main`.
+- Create a work branch (e.g. `docs/...`, `fix/...`, `feat/...`).
+- Open PRs targeting `dev` (never `main`).
+
+## Release / versioning prohibitions
+Unless the task explicitly asks for it, do **not**:
+- Create tags, GitHub Releases, or publish packages.
+- Bump versions or edit release metadata (for example `package.json` version).
+
+## Change discipline
+- Keep diffs minimal and scoped to the task.
+- Do not move/rename files or restructure folders unless explicitly requested.
+- Search before adding new helpers/utilities to avoid duplication.
+- Avoid drive-by refactors (formatting, naming, reorganization) unless requested.
+
+## Runtime vs Editor boundary
+- Runtime code must be build-safe (no unguarded `UnityEditor` dependencies).
+- Put editor tooling under `Runtime/Editor/` (this repo’s editor-only area) and/or guard editor-only code with `#if UNITY_EDITOR`.
+
+## When unsure
+If a change would require guessing architecture, conventions, or customer-facing API behavior:
+- Stop and ask for clarification rather than inventing a new pattern.
+
+## Reference
+- Architecture & structure overview: `docs/architecture.md`