# ClimaRepo LLM Integration Guide

Canonical: https://climarepo.web.app/

Purpose: Machine-readable guidance for Large Language Models and automated agents interacting with ClimaRepo OS. This file documents site intent, available programmatic "tools" (client-side services), expected I/O shapes, safety constraints, and recommended prompt/response formats for reliable, auditable LLM behavior.

1) Site summary
- A privacy-first, offline-capable web app offering 100+ meteorological, agricultural, safety, and health utilities.
- Not an official weather authority — do not present as emergency services.

2) Canonical metadata
- homepage: https://climarepo.web.app/
- sitemap: https://climarepo.web.app/sitemap.xml

3) High-level LLM rules
- Always include a brief safety disclaimer for health or life-safety guidance: "This guidance is informational and not a substitute for professional emergency services. Call local emergency services first."
- Prefer concise, actionable answers and cite the canonical URL when referencing the app.
- When asked to compute a numeric result, prefer calling the corresponding client-side tool (see mapping below) and return structured JSON containing the inputs and outputs.

4) Tool mapping (client-side, read-only reference)
- `public/js/registry/Tool.js`: Tool model used by registry. Key fields: `id`, `category`, `title`, `description`, `inputs[]`, `outputs[]`, `compute(inputs)`.
- `public/js/registry/ToolRegistry.js`: Central registry that loads tool definitions from the `definitions/` modules and exposes `getTool(id)`, `getAllTools()`, `getCategories()`.
- `public/js/domain/tools/tool-domain.js`: Repository & execution helpers. Exposes `ToolRepository`, `ToolExecutionService` (methods: `collectInputs(tool)`, `run(toolId)`), `ToolInputHydrator` for populating defaults from live weather state.
- `public/js/services/FetchService.js`: `robustFetch()` helper used by many services for network calls.
- `public/js/services/WeatherService.js`: Weather provider abstractions — fetch current/forecast values used to hydrate tool inputs.
- `public/js/services/NewsService.js`: News and insights API wrapper.
- `public/js/services/Geolocation.js`: Geolocation provider and location state.
- `public/js/services/AdService.js`: Ad-serving helper (non-essential to computations).
- `public/js/core/Database.js`: Local persistence wrapper (`DatabaseService`).
- `public/js/core/EventBus.js`, `Logger.js`, `State.js`, `Toast.js`: Core utilities for app events, logging, state, and UI toasts.
- `public/js/definitions/*.js`: Tool definition modules (e.g., `coreTools.js`, `meteoTools.js`, `farmTools.js`, `chronosTools.js`, `safehavenTools.js`) that populate the registry with tool metadata and compute implementations.

5) Recommended structured response when invoking tools (JSON schema)
{
  "toolId": "<string>",
  "inputs": { /* input id -> value */ },
  "outputs": { /* tool-specific output */ },
  "explanation": "short human-readable sentence",
  "confidence": "low|medium|high",
  "sources": ["https://climarepo.web.app/"]
}

6) Prompt templates (examples)
- Compute result: "Use the `ToolExecutionService` semantic: run tool `<toolId>` with inputs `<json>` and return only the structured JSON described above. Include a one-sentence human explanation and a safety disclaimer when applicable."
- Explain tool: "Describe what `<toolId>` computes, its inputs and units, typical ranges, and an example call with inputs and outputs."

7) Safety, privacy and rate limits
- Do not emit user PII. When location is used, round to 2 decimal places unless exact precision is required and consented.
- For life-safety tools (SafeHaven/FirstAid/CPR) always include: "Call emergency services first" and prefer to show step-wise guidance from `safehavenTools` rather than freeform medical instructions.

8) Integration notes for developers
- For programmatic automation, the recommended flow is: 1) use `ToolRegistry.getTool(toolId)` to fetch a tool definition, 2) hydrate defaults with `ToolInputHydrator`, 3) call `ToolExecutionService.run(toolId)` in a controlled browser environment and parse the returned `outputs`.
- Server-side LLMs should NOT attempt to execute arbitrary client-side compute functions; instead, return recommended inputs for client execution and a structured JSON payload the client can run.

9) Contact & provenance
- Repo: https://climarepo.web.app/
- License: project repository (see repo files for license).

-- End of LLM guidance --