chore: track .claude/rules/ and add self-maintenance instruction

Un-ignore .claude/rules/ so path-scoped rule files are shared via git.
Add instruction in CLAUDE.md to update rule files when modifying classes,
controllers, endpoints, or metrics — keeps rules current as part of
normal workflow rather than requiring separate maintenance.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/rules/app-classes.md

@@ -0,0 +1,109 @@
+---
+paths:
+  - "cameleer-server-app/**"
+---
+
+# App Module Key Classes
+
+`cameleer-server-app/src/main/java/com/cameleer/server/app/`
+
+## controller/ — REST endpoints
+
+- `AgentRegistrationController` — POST /register, POST /heartbeat, GET / (list), POST /refresh-token
+- `AgentSseController` — GET /sse (Server-Sent Events connection)
+- `AgentCommandController` — POST /broadcast, POST /{agentId}, POST /{agentId}/ack
+- `AppController` — CRUD /api/v1/apps, POST /{appId}/upload-jar, GET /{appId}/versions
+- `DeploymentController` — GET/POST /api/v1/apps/{appId}/deployments, POST /{id}/stop, POST /{id}/promote, GET /{id}/logs
+- `EnvironmentAdminController` — CRUD /api/v1/admin/environments, PUT /{id}/jar-retention
+- `ExecutionController` — GET /api/v1/executions (search + detail)
+- `SearchController` — POST /api/v1/search, GET /routes, GET /top-errors, GET /punchcard
+- `LogQueryController` — GET /api/v1/logs (filters: source, application, agentId, exchangeId, level, logger, q, environment, time range)
+- `LogIngestionController` — POST /api/v1/data/logs (accepts `List<LogEntry>` JSON array, each entry has `source`: app/agent). Logs WARN for: missing agent identity, unregistered agents, empty payloads, buffer-full drops, deserialization failures. Normal acceptance at DEBUG.
+- `CatalogController` — GET /api/v1/catalog (unified app catalog merging PG managed apps + in-memory agents + CH stats), DELETE /api/v1/catalog/{applicationId} (ADMIN: dismiss app, purge all CH data + PG record). Auto-filters discovered apps older than `discoveryttldays` with no live agents.
+- `ChunkIngestionController` — POST /api/v1/ingestion/chunk/{executions|metrics|diagrams}
+- `UserAdminController` — CRUD /api/v1/admin/users, POST /{id}/roles, POST /{id}/set-password
+- `RoleAdminController` — CRUD /api/v1/admin/roles
+- `GroupAdminController` — CRUD /api/v1/admin/groups
+- `OidcConfigAdminController` — GET/POST /api/v1/admin/oidc, POST /test
+- `SensitiveKeysAdminController` — GET/PUT /api/v1/admin/sensitive-keys. GET returns 200 with config or 204 if not configured. PUT accepts `{ keys: [...] }` with optional `?pushToAgents=true` to fan out merged keys to all LIVE agents. Stored in `server_config` table (key `sensitive_keys`).
+- `AuditLogController` — GET /api/v1/admin/audit
+- `MetricsController` — GET /api/v1/metrics, GET /timeseries
+- `DiagramController` — GET /api/v1/diagrams/{id}, POST /
+- `DiagramRenderController` — POST /api/v1/diagrams/render (ELK layout)
+- `ClaimMappingAdminController` — CRUD /api/v1/admin/claim-mappings, POST /test (accepts inline rules + claims for preview without saving)
+- `LicenseAdminController` — GET/POST /api/v1/admin/license
+- `AgentEventsController` — GET /api/v1/agent-events (agent state change history)
+- `AgentMetricsController` — GET /api/v1/agent-metrics (JVM/Camel metrics per agent instance)
+- `AppSettingsController` — GET/PUT /api/v1/apps/{appId}/settings
+- `ApplicationConfigController` — GET/PUT /api/v1/apps/{appId}/config (traced processors, route recording, sensitive keys per app)
+- `ClickHouseAdminController` — GET /api/v1/admin/clickhouse (ClickHouse admin, conditional on infrastructure endpoints)
+- `DatabaseAdminController` — GET /api/v1/admin/database (PG admin, conditional on infrastructure endpoints)
+- `DetailController` — GET /api/v1/detail (execution detail with processor tree)
+- `EventIngestionController` — POST /api/v1/data/events (agent event ingestion)
+- `RbacStatsController` — GET /api/v1/admin/rbac/stats
+- `RouteCatalogController` — GET /api/v1/routes/catalog (merged route catalog from registry + ClickHouse)
+- `RouteMetricsController` — GET /api/v1/route-metrics (per-route Camel metrics)
+- `ThresholdAdminController` — CRUD /api/v1/admin/thresholds
+- `UsageAnalyticsController` — GET /api/v1/admin/usage (ClickHouse usage_events)
+
+## runtime/ — Docker orchestration
+
+- `DockerRuntimeOrchestrator` — implements RuntimeOrchestrator; Docker Java client (zerodep transport), container lifecycle
+- `DeploymentExecutor` — @Async staged deploy: PRE_FLIGHT -> PULL_IMAGE -> CREATE_NETWORK -> START_REPLICAS -> HEALTH_CHECK -> SWAP_TRAFFIC -> COMPLETE. Container names are `{tenantId}-{envSlug}-{appSlug}-{replicaIndex}` (globally unique on Docker daemon). Sets per-replica `CAMELEER_AGENT_INSTANCEID` env var to `{envSlug}-{appSlug}-{replicaIndex}`.
+- `DockerNetworkManager` — ensures bridge networks (cameleer-traefik, cameleer-env-{slug}), connects containers
+- `DockerEventMonitor` — persistent Docker event stream listener (die, oom, start, stop), updates deployment status
+- `TraefikLabelBuilder` — generates Traefik Docker labels for path-based or subdomain routing. Also emits `cameleer.replica` and `cameleer.instance-id` labels per container for labels-first identity.
+- `PrometheusLabelBuilder` — generates Prometheus Docker labels (`prometheus.scrape/path/port`) per runtime type for `docker_sd_configs` auto-discovery
+- `ContainerLogForwarder` — streams Docker container stdout/stderr to ClickHouse with `source='container'`. One follow-stream thread per container, batches lines every 2s/50 lines via `ClickHouseLogStore.insertBufferedBatch()`. 60-second max capture timeout.
+- `DisabledRuntimeOrchestrator` — no-op when runtime not enabled
+
+## metrics/ — Prometheus observability
+
+- `ServerMetrics` — centralized business metrics: gauges (agents by state, SSE connections, buffer depths), counters (ingestion drops, agent transitions, deployment outcomes, auth failures), timers (flush duration, deployment duration). Exposed via `/api/v1/prometheus`.
+
+## storage/ — PostgreSQL repositories (JdbcTemplate)
+
+- `PostgresAppRepository`, `PostgresAppVersionRepository`, `PostgresEnvironmentRepository`
+- `PostgresDeploymentRepository` — includes JSONB replica_states, deploy_stage, findByContainerId
+- `PostgresUserRepository`, `PostgresRoleRepository`, `PostgresGroupRepository`
+- `PostgresAuditRepository`, `PostgresOidcConfigRepository`, `PostgresClaimMappingRepository`, `PostgresSensitiveKeysRepository`
+- `PostgresAppSettingsRepository`, `PostgresApplicationConfigRepository`, `PostgresThresholdRepository`
+
+## storage/ — ClickHouse stores
+
+- `ClickHouseExecutionStore`, `ClickHouseMetricsStore`, `ClickHouseMetricsQueryStore`
+- `ClickHouseStatsStore` — pre-aggregated stats, punchcard
+- `ClickHouseDiagramStore`, `ClickHouseAgentEventRepository`
+- `ClickHouseUsageTracker` — usage_events for billing
+
+## search/ — ClickHouse search and log stores
+
+- `ClickHouseLogStore` — log storage and query, MDC-based exchange/processor correlation
+- `ClickHouseSearchIndex` — full-text search
+
+## security/ — Spring Security
+
+- `SecurityConfig` — WebSecurityFilterChain, JWT filter, CORS, OIDC conditional
+- `JwtAuthenticationFilter` — OncePerRequestFilter, validates Bearer tokens
+- `JwtServiceImpl` — HMAC-SHA256 JWT (Nimbus JOSE)
+- `OidcAuthController` — /api/v1/auth/oidc (login-uri, token-exchange, logout)
+- `OidcTokenExchanger` — code -> tokens, role extraction from access_token then id_token
+- `OidcProviderHelper` — OIDC discovery, JWK source cache
+
+## agent/ — Agent lifecycle
+
+- `SseConnectionManager` — manages per-agent SSE connections, delivers commands
+- `AgentLifecycleMonitor` — @Scheduled 10s, LIVE->STALE->DEAD transitions
+- `SsePayloadSigner` — Ed25519 signs SSE payloads for agent verification
+
+## retention/ — JAR cleanup
+
+- `JarRetentionJob` — @Scheduled 03:00 daily, per-environment retention, skips deployed versions
+
+## config/ — Spring beans
+
+- `RuntimeOrchestratorAutoConfig` — conditional Docker/Disabled orchestrator + NetworkManager + EventMonitor
+- `RuntimeBeanConfig` — DeploymentExecutor, AppService, EnvironmentService
+- `SecurityBeanConfig` — JwtService, Ed25519, BootstrapTokenValidator
+- `StorageBeanConfig` — all repositories
+- `ClickHouseConfig` — ClickHouse JdbcTemplate, schema initializer