@cronicorn/mcp-server 1.4.5 → 1.5.1

package/dist/docs/technical/how-scheduling-works.md

@@ -0,0 +1,268 @@
+---
+id: how-scheduling-works
+title: How Scheduling Works
+description: Scheduler loop, Governor safety, and nextRunAt calculation
+tags: [assistant, technical, scheduler]
+sidebar_position: 2
+mcp:
+  uri: file:///docs/technical/how-scheduling-works.md
+  mimeType: text/markdown
+  priority: 0.85
+  lastModified: 2025-11-02T00:00:00Z
+---
+
+# How Scheduling Works
+
+This document explains how the Scheduler worker executes jobs and calculates next run times. If you haven't read [System Architecture](./system-architecture.md), start there for context on the dual-worker design.
+
+## The Scheduler's Job
+
+The Scheduler worker has one responsibility: execute endpoints on time, record results, and schedule the next run. It doesn't analyze patterns, make AI decisions, or try to be clever. It's a reliable execution engine.
+
+Every 5 seconds (configurable), the Scheduler wakes up and runs a **tick**:
+
+1. **Claim** due endpoints from the database
+2. **Execute** each endpoint's HTTP request
+3. **Record** results (status, duration, response body)
+4. **Calculate** when to run next using the Governor
+5. **Update** the database with the new schedule
+
+Then it goes back to sleep. Simple, predictable, fast.
+
+## The Tick Loop in Detail
+
+### Step 1: Claiming Due Endpoints
+
+The Scheduler asks the database: "Which endpoints have `nextRunAt <= now`?" 
+
+But there's a catch—in production, you might run multiple Scheduler instances for redundancy. To prevent two Schedulers from executing the same endpoint simultaneously, the claim operation uses a **lock**.
+
+Here's how claiming works:
+
+- Query for endpoints where `nextRunAt <= now` and `_lockedUntil <= now` (not currently locked)
+- Atomically update those endpoints to set `_lockedUntil = now + lockTtlMs` (typically 30 seconds)
+- Return the list of endpoint IDs that were successfully locked
+
+The lock TTL serves as a safety mechanism. If a Scheduler crashes while executing an endpoint, the lock expires and another Scheduler can claim it. This prevents endpoints from getting stuck if a worker dies mid-execution.
+
+The Scheduler claims up to `batchSize` endpoints per tick (default: 10). This provides flow control—if the system is backlogged, it processes endpoints in manageable batches rather than trying to execute hundreds at once.
+
+### Step 2: Executing the Endpoint
+
+For each claimed endpoint, the Scheduler:
+
+1. Reads the full endpoint configuration from the database
+2. Creates a run record with status `"running"` and the current attempt number
+3. Makes the HTTP request (GET, POST, etc.) to the endpoint's URL
+4. Waits for the response (up to the configured timeout)
+5. Records the outcome: success/failure, duration, status code, response body
+
+The response body is stored in the database. This is important—the AI Planner will read these response bodies later to make scheduling decisions. Structure your endpoint responses to include metrics the AI should monitor (queue depth, error rate, load indicators).
+
+### Step 3: Recording Results
+
+After execution completes (or times out), the Scheduler writes a complete run record:
+
+- Status: `"success"` or `"failure"`
+- Duration in milliseconds
+- HTTP status code
+- Response body (the JSON returned by your endpoint)
+- Error message (if failed)
+
+This creates a historical record. You can query past runs to see execution patterns, investigate failures, or debug scheduling behavior.
+
+### Step 4: The Governor Decides Next Run Time
+
+After recording results, the Scheduler needs to answer: "When should this endpoint run next?"
+
+This is where the **Governor** comes in. The Governor is a pure function that takes three inputs:
+
+- **Current time** (`now`)
+- **Endpoint state** (baseline schedule, AI hints, constraints, failure count)
+- **Cron parser** (for evaluating cron expressions)
+
+It returns a single output:
+
+- **Next run time** and **source** (why this time was chosen)
+
+The Governor is deterministic—same inputs always produce the same output. It makes no database calls, has no side effects, and contains no I/O. This makes it easy to test, audit, and understand.
+
+Let's walk through how the Governor makes its decision.
+
+### Building Scheduling Candidates
+
+The Governor starts by building a list of **candidates**—possible next run times based on different scheduling sources:
+
+**Baseline Candidate**
+
+Every endpoint has a baseline schedule. This is either:
+- A cron expression: `"0 */5 * * *"` → next cron occurrence after `now`
+- An interval: `300000ms` → `now + 300000ms` (with exponential backoff on failures)
+
+The baseline represents your intent. It never expires.
+
+If the endpoint uses interval-based scheduling and has failures, the Governor applies **exponential backoff**: `interval * 2^failureCount` (capped at 5 failures = 32x multiplier). This prevents hammering a failing endpoint while still retrying.
+
+**AI Interval Candidate**
+
+If there's an active AI interval hint (not expired), the Governor creates a candidate:
+- `now + aiHintIntervalMs`
+- Source: `"ai-interval"`
+
+This candidate only exists if `aiHintExpiresAt > now`. Expired hints are ignored.
+
+**AI One-Shot Candidate**
+
+If there's an active AI one-shot hint (not expired), the Governor creates a candidate:
+- `aiHintNextRunAt` (specific timestamp)
+- Source: `"ai-oneshot"`
+
+Again, only if `aiHintExpiresAt > now`.
+
+### Choosing the Winning Candidate
+
+Now the Governor has 1-3 candidates. Which one wins?
+
+**The rules:**
+
+1. **If both AI hints exist**: Choose the earliest between interval and one-shot (baseline ignored)
+2. **If only AI interval exists**: AI interval wins (baseline ignored)
+3. **If only AI one-shot exists**: Choose earliest between one-shot and baseline
+4. **If no AI hints exist**: Baseline wins
+
+This logic ensures that:
+- AI interval hints **override** baseline (enables tightening/relaxing schedule)
+- AI one-shot hints **compete** with other candidates (enables immediate runs)
+- Baseline is the fallback when AI has no opinion
+
+### Safety: Handling Past Candidates
+
+Sometimes a candidate time is in the past. This happens when:
+- Execution took longer than the interval
+- System was backlogged
+- One-shot hint targeted a time that already passed
+
+The Governor handles this by rescheduling from `now`:
+
+- **Interval-based** (baseline or AI interval): Add the interval to `now` to preserve cadence
+- **Cron-based**: Use cron.next() which handles past times correctly
+- **One-shot**: Floor to `now` (run immediately)
+
+This prevents the endpoint from being immediately reclaimed in the next tick, which would cause a tight execution loop.
+
+### Applying Constraints (Clamping)
+
+After choosing a candidate, the Governor applies **min/max interval constraints** (if configured):
+
+- **Min interval**: If `chosen < (now + minIntervalMs)`, move it forward to `now + minIntervalMs` (source becomes `"clamped-min"`)
+- **Max interval**: If `chosen > (now + maxIntervalMs)`, move it back to `now + maxIntervalMs` (source becomes `"clamped-max"`)
+
+These constraints are hard limits. They override even AI hints. Use them to enforce invariants like rate limits or maximum staleness.
+
+### The Pause Override
+
+After all candidate evaluation and clamping, the Governor checks one final thing: **Is the endpoint paused?**
+
+If `pausedUntil` is set and `pausedUntil > now`, the Governor returns:
+- `nextRunAt = pausedUntil`
+- Source: `"paused"`
+
+Pause **always wins**. It overrides baseline, AI hints, and constraints. This gives you an emergency brake to stop an endpoint immediately.
+
+### Step 5: Database Update
+
+The Scheduler writes back to the database:
+
+- `lastRunAt = now` (when this execution started)
+- `nextRunAt = governor result` (when to run next)
+- `failureCount`: reset to 0 on success, increment on failure
+- Clear expired AI hints (if `aiHintExpiresAt <= now`)
+
+The database update is atomic. If two Schedulers somehow claimed the same endpoint (shouldn't happen due to locks, but defensive programming), only one update succeeds.
+
+After the update, the endpoint's lock expires naturally (when `_lockedUntil` passes), and it becomes claimable again when `nextRunAt` arrives.
+
+## Safety Mechanisms
+
+The Scheduler includes several safety mechanisms to handle edge cases:
+
+### Zombie Run Cleanup
+
+A **zombie run** is a run record stuck in `"running"` status because the Scheduler crashed mid-execution.
+
+The Scheduler periodically (every few minutes) scans for runs where:
+- Status is `"running"`
+- Created more than `zombieThresholdMs` ago (default: 5 minutes)
+
+These runs are marked as `"timeout"` or `"cancelled"` to clean up the database and prevent confusion in the UI.
+
+### Lock Expiration
+
+The `_lockedUntil` field prevents double execution. Locks are short-lived (30 seconds by default). If a Scheduler crashes, the lock expires and another Scheduler can pick up the work.
+
+This means endpoints can't get permanently stuck. At worst, there's a delay equal to the lock TTL before another Scheduler claims the endpoint.
+
+### Past Candidate Protection
+
+As mentioned earlier, the Governor reschedules past candidates from `now` rather than allowing them to remain in the past. This prevents immediate reclaiming, which would create a tight loop.
+
+The Scheduler also has a second layer of protection: after calling the Governor, it checks if the returned `nextRunAt` is still in the past (due to slow execution). If so, it recalculates from the current time using the intended interval.
+
+This double-check ensures that even if execution is very slow, the system doesn't spiral into a reclaim loop.
+
+### Failure Count and Backoff
+
+When an endpoint fails repeatedly, the Governor applies exponential backoff to interval-based schedules:
+
+- 0 failures: Normal interval
+- 1 failure: 2x interval
+- 2 failures: 4x interval
+- 3 failures: 8x interval
+- 4 failures: 16x interval
+- 5+ failures: 32x interval (capped)
+
+This prevents hammering a failing service while still retrying. The backoff resets to 0 on the first success.
+
+## Sources: Tracing Scheduling Decisions
+
+Every scheduling decision records its **source**. This tells you why an endpoint ran at a particular time. Possible sources:
+
+- `"baseline-cron"`: Ran on cron schedule
+- `"baseline-interval"`: Ran on fixed interval
+- `"ai-interval"`: Ran using AI interval hint
+- `"ai-oneshot"`: Ran using AI one-shot hint
+- `"clamped-min"`: Chosen time was too soon, moved to min interval
+- `"clamped-max"`: Chosen time was too late, moved to max interval
+- `"paused"`: Endpoint is paused
+
+These sources are stored in run records and logs. When debugging "why did this endpoint run at 3:47 AM?", check the source. It shows the decision trail.
+
+## What Happens Between Ticks
+
+While the Scheduler sleeps (the 5 seconds between ticks), other things can happen:
+
+- The AI Planner might write new hints
+- You might update the endpoint configuration via the API
+- You might pause an endpoint
+- External systems might change state
+
+None of this disrupts the Scheduler. When it wakes up for the next tick, it reads fresh state from the database and makes decisions based on current reality.
+
+This is the power of database-mediated communication: the Scheduler and AI Planner stay in sync without ever talking directly.
+
+## Key Takeaways
+
+1. **The Scheduler is simple**: Claim, execute, record, schedule, repeat
+2. **The Governor is deterministic**: Pure function, same inputs = same output
+3. **AI hints override baseline**: This enables adaptation
+4. **Constraints are hard limits**: Min/max and pause override everything
+5. **Safety mechanisms prevent failures**: Locks, zombie cleanup, backoff, past protection
+6. **Sources provide auditability**: Every decision is traceable
+
+Understanding how scheduling works gives you the foundation to configure endpoints effectively, debug unexpected behavior, and reason about how AI adaptation affects execution timing.
+
+## Next Steps
+
+- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Learn how the AI Planner writes hints
+- **[Configuration and Constraints](./configuration-and-constraints.md)** - Guide to setting up endpoints safely
+- **[Reference](./reference.md)** - Quick lookup for fields, defaults, and sources

package/dist/docs/technical/reference.md

@@ -0,0 +1,404 @@
+---
+id: technical-reference
+title: Technical Reference
+description: Quick lookup for schemas, defaults, tools, and state transitions
+tags: [assistant, technical, reference]
+sidebar_position: 6
+mcp:
+  uri: file:///docs/technical/reference.md
+  mimeType: text/markdown
+  priority: 0.75
+  lastModified: 2025-11-02T00:00:00Z
+---
+
+# Reference
+
+Quick lookup for Cronicorn terminology, schema, defaults, and tools.
+
+## Glossary
+
+**Baseline Schedule**
+: The permanent schedule configured for an endpoint (cron expression or interval). Used when no AI hints are active. Never expires unless manually updated.
+
+**Governor**
+: Pure function that calculates the next run time for an endpoint. Takes current time, endpoint state, and cron parser as inputs. Returns timestamp and source.
+
+**Hint**
+: Temporary AI suggestion for scheduling (interval or one-shot). Has a TTL and expires automatically. Stored in `aiHint*` fields.
+
+**Nudging**
+: Updating `nextRunAt` immediately when AI writes a hint, so the change takes effect within seconds instead of waiting for the next baseline execution. Uses `setNextRunAtIfEarlier()`.
+
+**Claiming**
+: The Scheduler's process of acquiring locks on due endpoints to prevent double execution in multi-worker setups. Uses `_lockedUntil` field.
+
+**Tick**
+: One iteration of the Scheduler's loop (every 5 seconds). Claims due endpoints, executes them, records results, schedules next run.
+
+**Source**
+: The reason a particular next run time was chosen. Values: `baseline-cron`, `baseline-interval`, `ai-interval`, `ai-oneshot`, `clamped-min`, `clamped-max`, `paused`.
+
+**TTL (Time To Live)**
+: How long an AI hint remains valid before expiring. After expiration, the system reverts to baseline. Default: 60 minutes for intervals, 30 minutes for one-shots.
+
+**Exponential Backoff**
+: Automatic interval increase after failures: `baselineMs × 2^min(failureCount, 5)`. Applies only to baseline interval schedules, not AI hints or cron.
+
+**Zombie Run**
+: A run record stuck in `"running"` status because the Scheduler crashed mid-execution. Cleaned up after 5 minutes by default.
+
+**Sibling Endpoints**
+: Endpoints in the same job that can coordinate via `get_sibling_latest_responses()`.
+
+**Analysis Session**
+: Record of AI analysis for an endpoint, including tools called, reasoning, and token usage. Stored in `ai_analysis_sessions` table.
+
+## Schema: job_endpoints Table
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Unique endpoint identifier |
+| `jobId` | UUID | Parent job (for grouping and sibling queries) |
+| `tenantId` | UUID | Tenant for multi-tenancy |
+| `name` | String | Display name |
+| `description` | String | Optional context for AI |
+| `url` | String | HTTP endpoint to call |
+| `method` | Enum | HTTP method (GET, POST, PUT, PATCH, DELETE) |
+| `headersJson` | JSON | Request headers |
+| `bodyJson` | JSON | Request body (for POST/PUT/PATCH) |
+| `baselineCron` | String | Cron expression (mutually exclusive with interval) |
+| `baselineIntervalMs` | Integer | Fixed interval in milliseconds |
+| `minIntervalMs` | Integer | Minimum interval constraint (hard limit) |
+| `maxIntervalMs` | Integer | Maximum interval constraint (hard limit) |
+| `timeoutMs` | Integer | Request timeout |
+| `maxResponseSizeKb` | Integer | Response body size limit |
+| `maxExecutionTimeMs` | Integer | Max execution time for lock duration |
+| `aiHintIntervalMs` | Integer | AI-suggested interval (temporary) |
+| `aiHintNextRunAt` | Timestamp | AI-suggested one-shot time (temporary) |
+| `aiHintExpiresAt` | Timestamp | When AI hints expire |
+| `aiHintReason` | String | AI's explanation for hint |
+| `pausedUntil` | Timestamp | Pause until this time (null = not paused) |
+| `lastRunAt` | Timestamp | When endpoint last executed |
+| `nextRunAt` | Timestamp | When to run next (updated after each execution) |
+| `failureCount` | Integer | Consecutive failures (reset on success) |
+| `_lockedUntil` | Timestamp | Lock expiration for claiming |
+
+## Default Values
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| **Scheduler tick interval** | 5 seconds | How often Scheduler wakes up to claim endpoints |
+| **AI analysis interval** | 5 minutes | How often AI Planner discovers and analyzes endpoints |
+| **Lock TTL** | 30 seconds | How long claimed endpoints stay locked |
+| **Batch size** | 10 endpoints | Max endpoints claimed per tick |
+| **Zombie threshold** | 5 minutes | Runs older than this marked as timeout |
+| **AI hint TTL** | 60 minutes | Default for `propose_interval` |
+| **One-shot hint TTL** | 30 minutes | Default for `propose_next_time` |
+| **Timeout** | 30 seconds | Default request timeout |
+| **Max response size** | 100 KB | Default response body limit |
+| **Failure count cap** | 5 | Backoff capped at 2^5 = 32x |
+| **Min interval** | None | No minimum unless configured |
+| **Max interval** | None | No maximum unless configured |
+
+## AI Tool Catalog
+
+### Action Tools (Write Hints)
+
+#### propose_interval
+
+Adjust endpoint execution frequency.
+
+**Parameters**:
+- `intervalMs` (number, required): New interval in milliseconds
+- `ttlMinutes` (number, default: 60): How long hint is valid
+- `reason` (string, optional): Explanation for adjustment
+
+**Effect**: Writes `aiHintIntervalMs` and `aiHintExpiresAt`, nudges `nextRunAt`
+
+**Override behavior**: Overrides baseline (not one-shot)
+
+**Example**:
+```json
+{
+  "intervalMs": 30000,
+  "ttlMinutes": 15,
+  "reason": "Queue depth increasing - tightening monitoring"
+}
+```
+
+#### propose_next_time
+
+Schedule one-shot execution at specific time.
+
+**Parameters**:
+- `nextRunAtIso` (ISO 8601 string, required): When to run next
+- `ttlMinutes` (number, default: 30): How long hint is valid
+- `reason` (string, optional): Explanation
+
+**Effect**: Writes `aiHintNextRunAt` and `aiHintExpiresAt`, nudges `nextRunAt`
+
+**Override behavior**: Competes with baseline (earliest wins)
+
+**Example**:
+```json
+{
+  "nextRunAtIso": "2025-11-02T14:30:00Z",
+  "ttlMinutes": 5,
+  "reason": "Immediate investigation of failure spike"
+}
+```
+
+#### pause_until
+
+Pause execution temporarily or resume.
+
+**Parameters**:
+- `untilIso` (ISO 8601 string or null, required): Pause until time, or null to resume
+- `reason` (string, optional): Explanation
+
+**Effect**: Writes `pausedUntil`
+
+**Override behavior**: Overrides everything (highest priority)
+
+**Example**:
+```json
+{
+  "untilIso": "2025-11-02T15:00:00Z",
+  "reason": "Dependency unavailable until maintenance completes"
+}
+```
+
+### Query Tools (Read Data)
+
+#### get_latest_response
+
+Get most recent response body from this endpoint.
+
+**Parameters**: None
+
+**Returns**:
+```json
+{
+  "found": true,
+  "responseBody": { "queue_depth": 45, "status": "healthy" },
+  "timestamp": "2025-11-02T14:30:00Z",
+  "status": "success"
+}
+```
+
+#### get_response_history
+
+Get recent response bodies to identify trends.
+
+**Parameters**:
+- `limit` (number, default: 2, max: 10): Number of responses
+- `offset` (number, default: 0): Skip N newest for pagination
+
+**Returns**:
+```json
+{
+  "count": 2,
+  "hasMore": true,
+  "pagination": { "offset": 0, "limit": 2, "nextOffset": 2 },
+  "responses": [
+    {
+      "responseBody": { "queue_depth": 200 },
+      "timestamp": "2025-11-02T14:30:00Z",
+      "status": "success",
+      "durationMs": 120
+    }
+  ],
+  "hint": "More history available - call again with offset: 2"
+}
+```
+
+**Note**: Response bodies truncated at 1000 chars
+
+#### get_sibling_latest_responses
+
+Get latest responses from all endpoints in same job.
+
+**Parameters**: None
+
+**Returns**:
+```json
+{
+  "count": 3,
+  "siblings": [
+    {
+      "endpointId": "ep_456",
+      "endpointName": "Data Processor",
+      "responseBody": { "batch_id": "2025-11-02", "ready": true },
+      "timestamp": "2025-11-02T14:25:00Z",
+      "status": "success"
+    }
+  ]
+}
+```
+
+**Note**: Only returns endpoints with same `jobId`
+
+### Final Answer Tool
+
+#### submit_analysis
+
+Signal analysis completion and provide reasoning.
+
+**Parameters**:
+- `reasoning` (string, required): Analysis explanation
+- `actions_taken` (string[], optional): List of tools called
+- `confidence` (enum, optional): 'high' | 'medium' | 'low'
+
+**Returns**:
+```json
+{
+  "status": "analysis_complete",
+  "reasoning": "...",
+  "actions_taken": ["propose_interval"],
+  "confidence": "high"
+}
+```
+
+**Note**: Must be called last to complete analysis
+
+## Scheduling Sources
+
+Sources explain why a particular next run time was chosen:
+
+| Source | Meaning | Priority |
+|--------|---------|----------|
+| `paused` | Endpoint is paused, runs at `pausedUntil` | Highest (overrides all) |
+| `clamped-min` | Chosen time was too soon, moved to `now + minIntervalMs` | High |
+| `clamped-max` | Chosen time was too late, moved to `now + maxIntervalMs` | High |
+| `ai-interval` | AI interval hint overrode baseline | Medium |
+| `ai-oneshot` | AI one-shot hint won competition | Medium |
+| `baseline-cron` | Cron expression determined time | Low (default) |
+| `baseline-interval` | Fixed interval determined time | Low (default) |
+
+**Reading sources**: Check run records or logs to see why an endpoint ran at a particular time.
+
+## Constraint Interaction Matrix
+
+How different settings interact:
+
+| If you set... | AI interval hints... | AI one-shot hints... | Baseline... |
+|---------------|---------------------|---------------------|-------------|
+| `pausedUntil` | Ignored (pause wins) | Ignored (pause wins) | Ignored |
+| `minIntervalMs` | Clamped to minimum | Clamped to minimum | Clamped to minimum |
+| `maxIntervalMs` | Clamped to maximum | Clamped to maximum | Clamped to maximum |
+| Both AI hints active | Compete (earliest wins) | Compete (earliest wins) | Ignored |
+| Cron baseline | Ignored by AI | Competes with cron | Used when no hints |
+
+**Key insight**: Pause > Constraints > AI hints > Baseline
+
+## Field Constraints
+
+Limits enforced by the system:
+
+| Field | Min | Max | Units |
+|-------|-----|-----|-------|
+| `baselineIntervalMs` | 1,000 | None | Milliseconds (1 second minimum) |
+| `minIntervalMs` | 0 | None | Milliseconds |
+| `maxIntervalMs` | 0 | None | Milliseconds |
+| `timeoutMs` | 1,000 | 1,800,000 | Milliseconds (30 minutes max) |
+| `maxResponseSizeKb` | 1 | 10,000 | Kilobytes |
+| `maxExecutionTimeMs` | 1,000 | 1,800,000 | Milliseconds (30 minutes max) |
+| `failureCount` | 0 | None | Integer (capped at 5 for backoff) |
+| Hint TTL | 1 | None | Minutes (recommended: 5-240) |
+
+## Common Response Body Patterns
+
+Reusable structures for endpoint responses:
+
+### Health Status
+```json
+{
+  "status": "healthy" | "degraded" | "critical",
+  "timestamp": "2025-11-02T14:30:00Z"
+}
+```
+
+### Metrics
+```json
+{
+  "queue_depth": 45,
+  "processing_rate_per_min": 100,
+  "error_rate_pct": 1.2,
+  "avg_latency_ms": 150
+}
+```
+
+### Coordination Signals
+```json
+{
+  "ready_for_processing": true,
+  "batch_id": "2025-11-02",
+  "dependency_status": "healthy"
+}
+```
+
+### Cooldown Tracking
+```json
+{
+  "last_action_at": "2025-11-02T12:00:00Z",
+  "action_type": "cache_warm",
+  "cooldown_minutes": 60
+}
+```
+
+### Thresholds
+```json
+{
+  "current_value": 250,
+  "warning_threshold": 300,
+  "critical_threshold": 500
+}
+```
+
+## Quick Troubleshooting
+
+**Endpoint not running**:
+- Check `pausedUntil` (might be paused)
+- Check `nextRunAt` (might be scheduled far in future)
+- Check `_lockedUntil` (might be locked by crashed worker)
+
+**AI not adapting**:
+- Check `aiHintExpiresAt` (hints might be expired)
+- Check analysis sessions (AI might not see patterns)
+- Verify response bodies include metrics (AI needs data)
+- Check quota limits (might be exceeded)
+
+**Running too frequently**:
+- Check active AI interval hint
+- Verify `minIntervalMs` isn't set too low
+- Check for `propose_next_time` loops
+
+**Running too slowly**:
+- Check `maxIntervalMs` constraint
+- Check exponential backoff (high `failureCount`)
+- Verify baseline isn't too long
+
+## Useful Queries
+
+Check if endpoint is paused:
+```
+pausedUntil > now ? "Paused until {pausedUntil}" : "Active"
+```
+
+Check if AI hints are active:
+```
+aiHintExpiresAt > now ? "Active hints" : "No active hints"
+```
+
+Calculate current backoff multiplier:
+```
+failureCount > 0 ? 2^min(failureCount, 5) : 1
+```
+
+## Next Steps
+
+For detailed explanations, see:
+- **[System Architecture](./system-architecture.md)** - Understand the big picture
+- **[How Scheduling Works](./how-scheduling-works.md)** - Deep-dive into Governor and Scheduler
+- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Learn about hints and tools
+- **[Configuration Guide](./configuration-and-constraints.md)** - Set up endpoints correctly