feat: Implement runtime API cache store and related configurations

- Added RuntimeApiCacheStore for managing API cache entries in memory.
- Introduced StorageTarget enum to define various storage targets.
- Created StoredCacheEntry record to encapsulate cache entries.
- Defined SyncState enum to represent the synchronization state of cache entries.
- Added ControlPlaneConfigurationSource enum for different configuration sources.
- Developed ControlPlaneRuntimeConfig class for runtime configuration management.
- Implemented ControlPlaneStartupConfigResolver for resolving configuration from various sources.
- Created ControlPlaneStartupSettings to hold startup configuration values.
- Added ResolvedControlPlaneStartupConfig record to encapsulate resolved configuration.
- Implemented tests for batch client and cache client functionalities.
- Added tests for ControlPlaneStartupConfigResolver to validate configuration resolution logic.

docs/wiki/Troubleshooting.md

@@ -0,0 +1,116 @@
+# Troubleshooting
+
+## `NetworkPlugin has not been configured`
+
+No startup source produced both a control-plane base URL and token before another plugin requested `NetworkPlugin.client()`.
+
+Fix with one of:
+
+- environment variables: `KWB_CONTROL_PLANE_BASE_URL` and `KWB_CONTROL_PLANE_TOKEN`
+- JVM properties: `kweebec.controlPlane.baseUrl` and `kweebec.controlPlane.token`
+- local plugin config: `control-plane.json`
+- explicit startup call: `NetworkPlugin.configure(baseUrl, token)`
+
+Check which source configured the client:
+
+```java
+NetworkPlugin.configurationSource();
+```
+
+`Optional.empty()` means no source configured the shared client.
+
+## Startup Config Precedence
+
+Startup values are resolved in this order:
+
+1. environment variables
+2. JVM system properties
+3. `control-plane.json`
+
+Environment variables and JVM properties override only the fields they set. Missing fields can still come from a lower-priority source.
+
+## Config File Token Warning
+
+`control-plane.json` is a short-term local deployment fallback. Prefer environment variables for production or control-plane-provisioned servers.
+
+JVM `-D` properties are supported, but some host tooling can expose process arguments. Avoid logging launcher commands that contain tokens.
+
+## Auth Failures
+
+`AuthException` maps to HTTP `401` or `403`.
+
+Common causes:
+
+- missing token
+- expired or invalid token
+- inactive service account
+- token missing required ability
+- server-instance token trying to access a different instance route
+
+## Batch Futures Never Complete
+
+Likely causes:
+
+- batching scheduler has not started
+- `NetworkPlugin` is not loaded as the plugin main class
+- code enqueued calls but never called `batch().flush()` in tests
+- control plane does not expose `/api/v1/batch`
+
+In tests, call:
+
+```java
+client.batch().flush();
+```
+
+## Cached Reads Keep Returning Stale Data
+
+This can be expected behavior. If a refresh fails and an old value exists, cache APIs return the stale value and increment failed sync metadata.
+
+Check:
+
+```java
+cache.metadata(call, context)
+```
+
+Look at:
+
+- `failedSyncCount`
+- `lastError`
+- `syncState`
+
+## `PLAYER cache calls require PlayerCacheContext`
+
+Player storage is explicit. Use:
+
+```java
+new PlayerCacheContext(playerId, playerRef, entityStore)
+```
+
+Core-network will not infer player identity from `/players/{player}` URIs.
+
+## `NetworkApiDataComponent has not been registered`
+
+The player cache component is registered in `NetworkPlugin.setup()`.
+
+This error usually means:
+
+- tests are using player storage without plugin setup
+- `NetworkPlugin` is not the active Hytale plugin main class
+- code is accessing player cache before component registration
+
+## Asset Store Cache Does Nothing
+
+`ASSET_STORE` storage requires a plugin-provided `AssetStoreCacheAdapter`.
+
+Core-network does not create a generic Hytale asset store because Hytale assets require concrete asset classes, codecs, keys, and load/write behavior.
+
+## Manifest Rewrites During Gradle Tasks
+
+`processResources` depends on `updatePluginManifest`, which rewrites `src/main/resources/manifest.json` from Gradle properties.
+
+If the manifest changes unexpectedly after tests/builds, check:
+
+- `includes_pack` in `gradle.properties`
+- `version` in `gradle.properties`
+
+Avoid committing unrelated manifest churn.