@uptimizr/agent-core 1.1.1 → 1.2.0

package/AGENTS.md

@@ -9,17 +9,25 @@ The **framework-agnostic, browser-safe core** shared by every Uptimizr analytics
 the agent tool surface **once** (ADR 0050 §1) so `@uptimizr/mcp`, the dashboard assistant, and the
 demo assistant never drift apart. It owns:
 
-- the **read-only tool catalog** (`readTools`) — one entry per documented collector query endpoint,
-  **generated** from the `@uptimizr/metrics` semantic metric registry (ADR 0051 §1), so coverage of the
-  collector's read surface cannot drift;
+- the **read-only analytics catalog** (`readTools`) — one entry per documented collector query
+  endpoint, **generated** from the `@uptimizr/metrics` semantic metric registry (ADR 0051 §1), so
+  coverage of the collector's read surface cannot drift;
+- the **project-metadata catalog** (`writeTools`) — `annotate`, `define_term`, `save_analysis`
+  (ADR 0051 §5), `pin_panel` and `unpin_panel` (ADR 0051 §7), plus the four reads that make them
+  usable (`list_annotations`, `list_glossary`, `list_analyses`, `list_panels`). Deliberately a
+  **separate export**, never folded into `readTools`, so an integration's read-only stance stays
+  inspectable at a glance;
 - a headless **LLM provider-adapter interface** (`LlmProvider`) — messages + tool schemas in, tool
   calls or final text out;
 - the headless **tool-calling loop** (`runAgent`) — LLM ↔ tools ↔ collector.
 
-The core ships **no model and no key**. It only ever reads a consumer's **own** collector via the
-`CollectorClient` (`GET`-only, `x-api-key`).
+The core ships **no model and no key**. It only ever talks to a consumer's **own** collector via the
+`CollectorClient` (`x-api-key`). **Events are read-only**: nothing in this package can write, alter
+or delete an analytics event, and there is no ingestion path. The client's `post`/`put`/`delete`
+methods exist for the metadata write tools alone, and the collector gates those behind the
+`annotate` capability (ADR 0051 §9).
 
-## Tool catalog (read-only)
+## Analytics tool catalog (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this list -->
 
@@ -29,36 +37,94 @@ The core ships **no model and no key**. It only ever reads a consumer's **own**
 `position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
 `click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
 `mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
-`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
-`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
-`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
-`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
-`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
-`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
-`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
-`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
-`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `custom_event_vocabulary`,
+`camera_gestures`, `navigation_stats`, `backtrack_ratio`, `perf_summary`, `render_scale_truth`,
+`perf_distribution`, `fps_histogram`, `frame_time_percentiles`, `jank_rate`, `perf_churn`,
+`perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_summary`,
+`resource_percentiles`, `stability_counts`, `graphics_diagnostics`, `error_heatmap`,
+`rendering_technology`, `capability_changes`, `xr_rotation`, `xr_sources`, `xr_abandonment`,
+`xr_locomotion`, `xr_tracking_quality`, `boundary_heatmap`, `boundary_heatmap_stats`,
+`xr_boundary_contacts`, `ar_placement_time_to_place`, `ar_placement_attempts`,
+`ar_placement_surfaces`, `funnel`, `scene_retention`, `load_bounce_funnel`, `variant_leaderboard`,
+`insight_baseline`, `insight_movers`, `insight_anomalies`, `insight_significance`,
+`insight_scene_health`
+
+Only on a key holding `query:raw`, and only when the collector runs with
+`ENABLE_RAW_SESSION_RETENTION` (ADR 0003):
+
+`session_narrative`
 
 <!-- generated:registry-tool-names:end -->
 
 Each name is a metric in the collector's semantic metric registry (ADR 0051) and maps one-to-one to
 a documented query endpoint. Most accept `since`/`until` (epoch ms) plus endpoint-specific filters.
 
+## The `query` tool (the query DSL)
+
+One more tool sits after the generated list, and it is **not** per-metric: `query` (ADR 0051 §3).
+Its input _is_ the query DSL, so it can run any metric above with any filter that metric declares:
+
+```jsonc
+{
+  "v": 1,
+  "metric": "mesh_sources",
+  "range": { "since": 1757000000000, "until": 1757600000000 },
+  "filters": { "scene": "lobby", "cameraMode": "first-person" },
+  "limit": 20,
+  "format": "summary",
+}
+```
+
+- **`range` is required** — both ends, epoch ms. There is no unbounded query.
+- **`format` defaults to `table` here**, not `full`: this is a new, agent-facing surface, so the
+  envelope with the sample size and the truncation flag is the default.
+- The grammar is **closed**. Metrics, dimensions and filters are exactly the registry's vocabulary;
+  naming something outside it returns a `400` whose `issues[].accepted` lists what would have
+  worked. Read that rather than guessing again.
+- `dimensions` may be any subset a metric declares **when** its measure is a portable count —
+  event counts, mesh and interaction tallies, input actions, camera gestures. A spatial heatmap or a
+  percentile is computed at one fixed grain and refuses anything else, naming the grain it supports.
+- **`compare`** — another `{ range }` or `{ segment }`; the result comes back joined on the
+  dimension key as `{ current, previous, delta, deltaPct }`, with a significance test where the
+  measure is a count and both windows clear the metric's minimum. Never subtract two results by hand.
+- **`explain: true`** — the compiled plan instead of the rows: the tier, the SQL with its parameters
+  left unbound, `params` by name and type (never value), `rowsScanned`, and `warnings` (a capture
+  channel that produced nothing, a sample below the metric's minimum, a truncated result).
+- **`drillQuery`** — every row of a `summary` carries the whole query narrowed to that row, ready to
+  send straight back.
+- `order` takes a measure column, and only where the result is a ranked list.
+
+It reaches the collector as `GET /api/v1/query?q=<url-encoded JSON>`, so `CollectorClient` stays
+`GET`-only — an Uptimizr agent remains structurally incapable of writing.
+
+## Non-metric reads
+
+`readTools` is generated from the metric registry, with one deliberate exception: collector reads
+that are **configuration rather than measurements** and so have no registry entry
+(`nonRegistryTools.ts`). Today that is `list_subscriptions` (ADR 0051 §6) — the project's
+standing conditional subscriptions, what they watch for and how each last went. It takes no
+arguments and no time range. Creating or deleting a subscription needs the `annotate` capability
+and is not available as a tool; do it over plain HTTP.
+
 ## Result formats (`format`)
 
 Every **aggregate** tool in the catalog declares a `format` argument — `full | table | summary`.
 It picks the envelope the rows arrive in and filters nothing (ADR 0051 §2). The collector's
 `preSerialization` hook does the shaping, so the tool definitions stay pure `buildRequest` functions.
 
-| `format`  | Returns                                                                                                                                                                                         | Use it when                                                        |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `summary` | A bounded digest — `ranked` top rows, a `series` trend, merged spatial `clusters` or a single `record` — with shares, a sample size, the metric's `caveats` and a templated `reading` sentence. | **The default choice when a model will read the result.**          |
-| `table`   | `{ meta, rows }`: the rows plus metric, range, applied filters, sample size, row count, a truncation flag and the registry's limits.                                                            | You need every row _and_ the context to judge how far to trust it. |
-| `full`    | The bare rows, unchanged.                                                                                                                                                                       | You are post-processing the rows yourself. Today's default.        |
+**`buildRequest` applies `DEFAULT_TOOL_FORMAT` (`table`) when the caller names no format** and
+sends it explicitly, so the collector's own default stays `full` and the dashboard is unaffected.
+A tool's `outputSchema` describes all three envelopes, so whichever one comes back validates.
+
+| `format`  | Returns                                                                                                                                                                                         | Use it when                                                                     |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `summary` | A bounded digest — `ranked` top rows, a `series` trend, merged spatial `clusters` or a single `record` — with shares, a sample size, the metric's `caveats` and a templated `reading` sentence. | **Ask for it** whenever a model reads the result and you do not need every row. |
+| `table`   | `{ meta, rows }`: the rows plus metric, range, applied filters, sample size, row count, a truncation flag and the registry's limits.                                                            | **The default** — every row _and_ the context to judge it.                      |
+| `full`    | The bare rows, unchanged, with no envelope at all.                                                                                                                                              | You are post-processing the rows yourself.                                      |
 
 - `summary` is capped at the metric's `limits.maxSummaryRows`, which is what makes a heatmap, voxel
   cloud or long leaderboard safe to hand a model at all. This matters most for the **local** backend:
-  a 4-bit 7–8B model's whole context can be filled by one `full` heatmap.
+  a 4-bit 7–8B model's whole context can be filled by one heatmap's rows, in `full` or in `table`.
 - `reading` and `caveats` are templated from the registry's column semantics by pure code — no model
   — so identical rows always produce identical words. Quote them rather than re-deriving them.
 - Shares appear only where the measure can honestly be summed; an FPS or ratio metric reports
@@ -66,17 +132,90 @@ It picks the envelope the rows arrive in and filters nothing (ADR 0051 §2). The
   `cellSize` for world space.
 - `session_meta` and `scene_representation` are single stored records, not aggregations, and declare
   no `format`.
-- `full` remains the generated catalog's default so that existing consumers (the dashboard) are
-  unaffected. Pass `format: "summary"` explicitly from an agent path; the default flip is a separate,
-  documented change.
+- The **tools** default to `table`; the collector still defaults to `full`, so a consumer that calls
+  the HTTP endpoint directly (the dashboard) is unaffected. `table` is self-describing but not
+  bounded — its `meta` costs a fixed ~200 characters and the rows are still all of them — so pass
+  `format: "summary"` when the result could be large.
+
+## Project context (ADR 0051 §5)
+
+Read `GET /api/v1/context` **before** the first question and put a rendering of it in the system
+prompt. It is the only read that describes the project rather than the API: the real scene ids and
+named region ids, the custom events the application emits with their `props` keys and coarse types,
+top meshes, bound input actions, data freshness, retention flags, and `metrics.disabledByCapture` —
+metrics that return empty because their capture channel is off, not because nothing happened.
+
+`renderContextForPrompt(document)` turns it into a compact block (~1.5 k characters, capped and
+truncated on a line boundary) that a 1–3 B local model can carry alongside the tool schemas. It is
+pure, tolerant of a partial or unfamiliar document, and returns `""` when there is nothing to say —
+so a collector too old to serve the endpoint degrades to the prompt you had before rather than
+failing. Append it unconditionally.
+
+## Packaged methodology skills (ADR 0051 §7)
+
+A prompt names tools; a **skill** carries the method. Each one is an Agent Skills file,
+`skills/<name>/SKILL.md`, shipped in this tarball: frontmatter declaring the tools it relies on,
+the key capabilities it needs and the arguments it takes, and a body of numbered steps — orient on
+`uptimizr://context`, start from the score, test the change before calling it real, date it, and
+end with recommendations plus something worth keeping. Read one before you improvise:
+`skills/weekly-scene-health/SKILL.md`.
+
+<!-- generated:registry-skill-names:start — generated by `pnpm gen:docs`; edit the SKILL.md files, not this list -->
+
+- `attention_hotspots` (scene (required), range) — Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.
+  Method: `skills/attention-hotspots/SKILL.md`. Tools: `camera_heatmap`, `flow_links`, `click_rays`, `top_meshes`, `mesh_dwell`, `mesh_blind_spots`, `query`.
+- `conversion_investigation` (scene, range) — Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes.
+  Method: `skills/conversion-investigation/SKILL.md`. Tools: `funnel`, `load_bounce_funnel`, `scene_retention`, `variant_leaderboard`, `dead_clicks`, `rage_clicks`, `mesh_reachability`, `flow_links`, `insight_significance`, `insight_movers`, `query`.
+- `performance_regression_triage` (scene, range) — Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.
+  Method: `skills/performance-regression-triage/SKILL.md`. Tools: `insight_movers`, `insight_anomalies`, `insight_significance`, `insight_baseline`, `perf_summary`, `perf_distribution`, `frame_time_percentiles`, `jank_rate`, `perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_percentiles`, `render_scale_truth`, `rendering_technology`, `query`.
+- `weekly_scene_health` (scene, range) — A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.
+  Method: `skills/weekly-scene-health/SKILL.md`. Tools: `insight_scene_health`, `insight_movers`, `insight_baseline`, `insight_significance`, `insight_anomalies`, `event_counts`, `timeseries`, `perf_summary`, `top_meshes`, `list_sessions`, `query`.
+- `xr_comfort_audit` (scene, range) — Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.
+  Method: `skills/xr-comfort-audit/SKILL.md`. Tools: `xr_rotation`, `xr_locomotion`, `xr_abandonment`, `xr_sources`, `xr_tracking_quality`, `xr_boundary_contacts`, `boundary_heatmap_stats`, `insight_scene_health`, `insight_movers`, `query`.
+
+<!-- generated:registry-skill-names:end -->
+
+`AGENT_SKILLS` is those files compiled to data (`skills.generated.ts`, by
+`scripts/gen-agent-skills.mjs`) — this package is browser-safe and never reads them from disk at
+runtime. Each entry carries the title, description, tools, capabilities, arguments and a pure
+`render(args)` producing the single user turn. `getAgentSkill(name)` resolves one by either
+spelling (`xr_comfort_audit` or `xr-comfort-audit`), and `xr_comfort_review` still resolves to
+`xr_comfort_audit` for clients that saved the pre-#316 name.
+
+Three consumers drive the same text and must not drift: `@uptimizr/mcp` registers each as an MCP
+prompt template, `uptimizr agent report --skill` seeds its headless transcript with it, and the
+assistant offers it as a starter prompt. **Reword the SKILL.md and run `pnpm gen:skills`** — never
+copy a skill's text anywhere else.
+
+## Shared system-prompt fragments
+
+`ANALYTICS_AGENT_GUIDELINES` is what every analytics agent says about the _data_ — figures come
+from tools and are never invented, everything is aggregate and privacy-preserving, timestamps are
+epoch milliseconds, a tool error is explained rather than papered over. `renderCurrentTimeLine(nowMs)`
+gives the model a clock so it can resolve "this week" into `since`/`until`. The browser assistant
+and the report CLI both build their system prompt from these plus their own role sentence; only the
+role and the output format legitimately differ.
 
 ## Rules for agents
 
-- **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event
-  tools. The surface is aggregate-only; no data leaves the consumer's infrastructure (ADR 0003 /
-  ADR 0017). A new tool = a new **metric registry entry** in `@uptimizr/metrics` for a documented query
-  endpoint — never a hand-written catalog entry here — and no aggregation/business logic (that lives
-  in the collector, ADR 0005).
+- **Events are read-only; privacy-preserving throughout.** Never add an ingestion tool, an
+  event-mutating tool, or a raw per-session event tool. The analytics surface is aggregate-only and
+  no data leaves the consumer's infrastructure (ADR 0003 / ADR 0017). A new analytics tool = a new
+  **metric registry entry** in `@uptimizr/metrics` for a documented query endpoint — never a
+  hand-written catalog entry here — and no aggregation/business logic (that lives in the collector,
+  ADR 0005).
+- **Writes stay in `writeTools`, and stay metadata.** The only writable surface is project metadata
+  (annotations, glossary, saved analyses, pinned panels), each call needs an `annotate` key, each is
+  bounded at the collector's edge and audited there. Never add a write tool to `readTools`, and
+  never add one that reaches a non-metadata endpoint.
+- **A pinned panel is metadata too.** `pin_panel` stores a **spec** — a metric id, a chart name,
+  some column names — that the dashboard renders with panels it already ships; no module is loaded
+  and nothing is evaluated, so pinning does not widen the dashboard's trust boundary (ADR 0041).
+  Send the same `query` document the `query` tool takes, with `range: "inherit"` so the panel
+  follows the dashboard's own time filter, and a `chart` the metric's grain supports — the collector
+  refuses the rest and names the charts that would have worked. Read `list_panels` before pinning,
+  so you extend the dashboard rather than duplicate it; `unpin_panel` removes a panel for
+  **everyone** on the project, so never unpin one you have not read.
 - **Browser-safe.** No Node dependencies, no `types: ["node"]`. At runtime this package uses `zod`
   plus the pure, data-only `@uptimizr/metrics` package — **never** `@uptimizr/db`, which owns the
   DuckDB store and its ~37 MB native binding. `src/__tests__/browserSafety.test.ts` bundles the
@@ -84,21 +223,69 @@ It picks the envelope the rows arrive in and filters nothing (ADR 0051 §2). The
   if `@uptimizr/db` (or anything else with a native/optional binary dependency) reappears in the
   manifest. Anything that needs `process.env`, stdio, or the filesystem belongs in a consumer
   package (e.g. `@uptimizr/mcp`), not here.
+- **Start from an insight primitive on an open-ended question.** "How are things?" does not mean
+  "call thirty tools": `insight_scene_health` says _which scene_ to look at (six weighted factors,
+  each naming the metric, raw value and project baseline behind it; 50 is the project norm, not a
+  pass mark), `insight_movers` compares every comparable metric with the previous equal window and
+  ranks the changes by how unusual each is, and `insight_baseline` says whether a level is outside
+  normal for that scene. Two fields decide whether a mover is reportable: `direction` is the
+  registry's opinion of what a _rise_ means (so a rise in a `down` metric is a regression, not an
+  improvement), and `aboveMinSample: false` means the delta is arithmetic but not evidence — those
+  rows are returned rather than dropped, and must never be reported as findings.
+- **Then `insight_anomalies` to put a date on it.** `insight_movers` compares two windows you
+  chose; `insight_anomalies` walks one metric's whole series and names the buckets that do not
+  belong — `spike` / `drop` for a single bucket far from the ones before it, and `shift` at the
+  bucket where the level moved and _stayed_ moved, which is the shape a release regression has and
+  the one no per-bucket threshold can see. Quote `bucketStart`, and read `contributor`: where the
+  metric declares a dimension it can be split by, the row names the mesh, source, input action,
+  event type or scene holding the largest share of the excess. Its `z` is in standard deviations
+  while `insight_movers`' is the same ratio unscaled, so the two columns are not comparable.
+- **Call `insight_significance` before calling a single change real.** It reports the effect, a 95%
+  interval and a p-value for one metric across two windows, with the test chosen from what the
+  measure is. Read `ci95` before `p` — an interval straddling 0 means you cannot tell yet — and
+  read `powerNote`, which distinguishes "no effect" from "not enough data". It compares two
+  _windows_, not two segments.
 - Tool definitions are pure (`buildRequest`) and must stay unit-testable without a live collector.
 - The 20 tool names (and argument schemas) that shipped before the registry are a public contract:
   `src/__tests__/shippedToolCompat.test.ts` pins them against a frozen fixture. Widening a tool with
   a new **optional** argument is fine; renaming one or making an argument required is not.
 - Keep provider adapters thin and out of this package: implement `LlmProvider` in the consumer.
+- `ProviderResponse.usage` is **optional on every field**: a provider may report neither, one or
+  both token counts, and a local backend reports nothing. Treat a missing number as "not reported",
+  never as zero — a cost line that prints `0` when nothing was measured is a lie.
 
 ## Programmatic API
 
-`readTools`, `coreReadTools`, `selectReadTools(kind)`, `filterReadTools(names)`,
+`readTools`, `rawTools`, `coreReadTools`, `selectReadTools(kind)`, `filterReadTools(names)`,
 `registryToTools(metrics?)`, `createCollectorClient(config)`, `toToolSchemas(tools?)`,
-`runAgent(options)`, plus the `LlmProvider` / `AgentMessage` / `AgentToolCall` /
-`ProviderResponse` types.
+`runAgent(options)`, `renderContextForPrompt(context, nowMs?)`, `AGENT_SKILLS` /
+`getAgentSkill(name)` / `renderAgentSkill(name, args)`, `ANALYTICS_AGENT_GUIDELINES` /
+`renderCurrentTimeLine(nowMs)`, plus the `LlmProvider` / `AgentMessage` / `AgentToolCall` /
+`ProviderResponse` / `ProviderUsage` / `AgentSkill` / `PromptContextDocument` types.
+
+Metadata writes (ADR 0051 §5/§7): `writeTools`, `mutatingWriteTools`, the individual
+`annotateTool` / `defineTermTool` / `saveAnalysisTool` / `pinPanelTool` / `unpinPanelTool` /
+`listAnnotationsTool` / `listGlossaryTool` / `listAnalysesTool` / `listPanelsTool`, the `WriteTool`
+type and `WriteNotSupportedError` (thrown when a hand-built read-only client has no write
+transport). Each has an `execute(client, args)` rather than a `buildRequest`, because a write is one
+call rather than a request description. `pin_panel` and `unpin_panel` mutate; `list_panels` does
+not, and `mutatingWriteTools` is the filtered view. `unpin_panel` is the only tool here that uses
+`CollectorClient.delete`.
+
+The catalog is 77 tools on a plain `query` key. A small local model cannot hold every schema in its
+function-calling prompt — hand a run `coreReadTools` or `filterReadTools([...])` rather than the
+full catalog.
+
+### Capability-gated tools
 
-The catalog is ~69 tools. A small local model cannot hold every schema in its function-calling
-prompt — hand a run `coreReadTools` or `filterReadTools([...])` rather than the full catalog.
+`readTools` is the **`query`** surface — every tool a plain read key may call. `rawTools` is
+generated from the registry metrics whose endpoint declares `capability: "query:raw"` (today just
+`session_narrative`, the compacted account of one session) and is kept separate on purpose: the
+capability belongs to the _key the agent was handed_, not to the agent. Register it only after
+confirming the key holds `query:raw` via `GET /api/v1/whoami` — a tool that always answers `403`
+costs a model a turn and invites a retry. The collector refuses those endpoints unless it also runs
+with `ENABLE_RAW_SESSION_RETENTION`, so the capability is necessary but never sufficient
+(ADR 0003 / ADR 0051 §7).
 
 ## More
 

package/README.md

@@ -3,21 +3,27 @@
 The **framework-agnostic, browser-safe core** for Uptimizr analytics agents. It defines the agent
 tool surface **once** so every consumer — the [`@uptimizr/mcp`](../mcp/README.md) server, the
 dashboard assistant, and the backend-less demo assistant — asks the same questions of the same
-read-only collector query API (ADR 0050 §1).
+collector API (ADR 0050 §1).
 
-It owns three things:
+It owns four things:
 
-1. **The read-only tool catalog** (`readTools`) — one entry per documented aggregate query
+1. **The read-only analytics catalog** (`readTools`) — one entry per documented aggregate query
    endpoint. Pure Zod shapes, no Node dependencies, unit-testable without a live collector.
-2. **A headless LLM provider-adapter interface** (`LlmProvider`) — send messages + tool schemas,
+2. **The project-metadata catalog** (`writeTools`) — `annotate`, `define_term`, `save_analysis` and
+   their three read siblings (ADR 0051 §5). A deliberately **separate** export, never folded into
+   `readTools`, so an integration's read-only stance stays inspectable at a glance.
+3. **A headless LLM provider-adapter interface** (`LlmProvider`) — send messages + tool schemas,
    receive tool calls or a final answer. The core ships **no model and no key**; adapters
    (WebLLM/WebGPU, an OpenAI-compatible or Anthropic endpoint) are user-selected and
    user-controlled (ADR 0050 §4).
-3. **The headless tool-calling loop** (`runAgent`) — drives the LLM ↔ tools ↔ collector round trip,
+4. **The headless tool-calling loop** (`runAgent`) — drives the LLM ↔ tools ↔ collector round trip,
    framework-agnostic and runnable in a browser, a Node service, a CLI, or a bot.
 
-Everything here is **strictly read-only**: the loop only ever issues collector `GET`s through the
-catalog. There are **no** ingestion, mutation, or raw per-session event tools (ADR 0003 / ADR 0017).
+**Events are read-only**: nothing here can write, alter or delete an analytics event, and there are
+no ingestion or raw per-session event tools (ADR 0003 / ADR 0017 / ADR 0051 §9). The agent loop
+issues collector `GET`s only. The metadata tools are the single writable surface — they reach three
+metadata endpoints and nothing else, each call needs an `annotate` key, and the collector bounds and
+audits every one.
 
 ## Install
 
@@ -59,7 +65,7 @@ const result = await runAgent({
 console.log(result.content); // the model's final answer
 ```
 
-## Tool catalog (read-only)
+## Analytics tool catalog (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this table -->
 
@@ -69,21 +75,29 @@ console.log(result.content); // the model's final answer
 `position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
 `click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
 `mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
-`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
-`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
-`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
-`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
-`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
-`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
-`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
-`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
-`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `custom_event_vocabulary`,
+`camera_gestures`, `navigation_stats`, `backtrack_ratio`, `perf_summary`, `render_scale_truth`,
+`perf_distribution`, `fps_histogram`, `frame_time_percentiles`, `jank_rate`, `perf_churn`,
+`perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_summary`,
+`resource_percentiles`, `stability_counts`, `graphics_diagnostics`, `error_heatmap`,
+`rendering_technology`, `capability_changes`, `xr_rotation`, `xr_sources`, `xr_abandonment`,
+`xr_locomotion`, `xr_tracking_quality`, `boundary_heatmap`, `boundary_heatmap_stats`,
+`xr_boundary_contacts`, `ar_placement_time_to_place`, `ar_placement_attempts`,
+`ar_placement_surfaces`, `funnel`, `scene_retention`, `load_bounce_funnel`, `variant_leaderboard`,
+`insight_baseline`, `insight_movers`, `insight_anomalies`, `insight_significance`,
+`insight_scene_health`
+
+Only on a key holding `query:raw`, and only when the collector runs with
+`ENABLE_RAW_SESSION_RETENTION` (ADR 0003):
+
+`session_narrative`
 
 <!-- generated:registry-tool-names:end -->
 
 `readTools` is **generated** from the semantic metric registry in `@uptimizr/metrics`
 ([ADR 0051](https://github.com/RaananW/Uptimizr/blob/main/docs/adr/0051-ai-first-analytics-layer.md) §1):
-one tool per metric the collector serves on a read endpoint — **69** today, covering sessions and
+one tool per metric the collector serves on a read endpoint — **75** on a plain `query` key today,
+plus `session_narrative` behind `query:raw` — covering sessions and
 scenes, pointer/world/gaze/camera heatmaps, mesh attention and blind spots, dead and rage clicks,
 navigation and desire lines, performance (FPS distribution, jank, compile stalls, per-device and
 per-scene), errors and stability, XR/AR comfort and placement, and conversion (funnel, scene
@@ -100,8 +114,10 @@ Each tool carries:
   caveats (sample-size limits, which capture channel must be on);
 - an **input schema** built from the endpoint's filters — most accept `since`/`until` (epoch ms)
   plus `scene`, `session`, `source`, `bins`, `cellSize`, `limit`, `cameraMode`, `region`, …;
-- an **output schema** (`{ rows: Row[] }`) derived from the metric's row schema, which
-  `@uptimizr/mcp` registers as the MCP `outputSchema`.
+- an **output schema** derived from the metric's row schema and the `format` result envelopes —
+  `{ rows }`, the `{ meta, rows }` table envelope, or a `summary` digest — which `@uptimizr/mcp`
+  registers as the MCP `outputSchema`. A tool asks for `table` (`DEFAULT_TOOL_FORMAT`) unless the
+  caller names another format.
 
 The registry lives in `@uptimizr/metrics`, a dependency-free package (`zod` +
 `@uptimizr/schema`), so installing this one never downloads a database driver: `@uptimizr/db` and
@@ -109,11 +125,31 @@ its ~37 MB native DuckDB binding are **not** a dependency. Two tests keep that t
 asserts no `node:` built-in or DuckDB driver can reach a browser build, and a manifest test fails
 if any package with a native or optional binary dependency reappears.
 
+## Methodology skills
+
+The packaged investigations (ADR 0051 §7) — the same ones `@uptimizr/mcp` serves as prompt
+templates and `uptimizr agent report --skill` runs headlessly. Each is an Agent Skills file under
+`skills/<name>/SKILL.md` in this package; `AGENT_SKILLS` is those files compiled to data, and
+`getAgentSkill(name).render({ scene })` returns the user turn. `*` marks a required argument.
+
+<!-- generated:registry-skills:start — generated by `pnpm gen:docs`; edit the SKILL.md files, not this list -->
+
+| Skill                           | Arguments          | What it produces, and when to use it                                                                                                                                                                                                                                                                                                                                                                                                                     | Tools its method names                                                                                                                                                                                                                                                                                            |
+| ------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `attention_hotspots`            | `scene*`, `range?` | Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.                                                                                       | `camera_heatmap`, `flow_links`, `click_rays`, `top_meshes`, `mesh_dwell`, `mesh_blind_spots`, `query`                                                                                                                                                                                                             |
+| `conversion_investigation`      | `scene?`, `range?` | Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes. | `funnel`, `load_bounce_funnel`, `scene_retention`, `variant_leaderboard`, `dead_clicks`, `rage_clicks`, `mesh_reachability`, `flow_links`, `insight_significance`, `insight_movers`, `query`                                                                                                                      |
+| `performance_regression_triage` | `scene?`, `range?` | Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.                                                             | `insight_movers`, `insight_anomalies`, `insight_significance`, `insight_baseline`, `perf_summary`, `perf_distribution`, `frame_time_percentiles`, `jank_rate`, `perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_percentiles`, `render_scale_truth`, `rendering_technology`, `query` |
+| `weekly_scene_health`           | `scene?`, `range?` | A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.                        | `insight_scene_health`, `insight_movers`, `insight_baseline`, `insight_significance`, `insight_anomalies`, `event_counts`, `timeseries`, `perf_summary`, `top_meshes`, `list_sessions`, `query`                                                                                                                   |
+| `xr_comfort_audit`              | `scene?`, `range?` | Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.                                                                         | `xr_rotation`, `xr_locomotion`, `xr_abandonment`, `xr_sources`, `xr_tracking_quality`, `xr_boundary_contacts`, `boundary_heatmap_stats`, `insight_scene_health`, `insight_movers`, `query`                                                                                                                        |
+
+<!-- generated:registry-skills:end -->
+
 ## API
 
 | Export                         | Purpose                                                              |
 | ------------------------------ | -------------------------------------------------------------------- |
-| `readTools`                    | The read-only tool catalog (one entry per query endpoint).           |
+| `readTools`                    | The read-only analytics catalog (one entry per query endpoint).      |
+| `writeTools`                   | The `annotate`-gated project-metadata tools (ADR 0051 §5).           |
 | `coreReadTools`                | Focused subset for small local models (a filtered view, not a copy). |
 | `selectReadTools(kind)`        | Pick `"core"` or `"full"`.                                           |
 | `filterReadTools(names)`       | Narrow the catalog to specific tool names, in catalog order.         |

package/dist/client.d.ts

@@ -1,13 +1,26 @@
 /** A query-string parameter map. `undefined` values are omitted from the request. */
 export type QueryParams = Record<string, string | number | undefined>;
 /**
- * A minimal **read-only** HTTP client over the collector query API. It performs
- * `GET` requests only and holds no business logic — it is a thin transport that
- * mirrors the dashboard's `CollectorApi` so an agent reads the same aggregated
- * results a human would (ADR 0005 / ADR 0017).
+ * A minimal HTTP client over the collector API. It holds no business logic — it
+ * is a thin transport that mirrors the dashboard's `CollectorApi` so an agent
+ * reads the same aggregated results a human would (ADR 0005 / ADR 0017).
+ *
+ * `get` is the whole analytics surface: **events are read-only**, and nothing
+ * here can write, alter or delete one (ADR 0051 §9). The three write methods
+ * exist for exactly one caller — the metadata write tools of #310 (annotations,
+ * glossary, saved analyses) — which the MCP server registers only when the key
+ * holds `annotate`. They are optional so a hand-built read-only client is still
+ * a valid `CollectorClient`; {@link writeTools} reports a clear error instead of
+ * calling a method that is not there.
  */
 export interface CollectorClient {
     get(path: string, params?: QueryParams): Promise<unknown>;
+    /** Create a metadata row. Used only by the `annotate` write tools. */
+    post?(path: string, body: unknown): Promise<unknown>;
+    /** Upsert a metadata row (the glossary). Used only by the `annotate` write tools. */
+    put?(path: string, body: unknown): Promise<unknown>;
+    /** Delete a metadata row. Used only by the `annotate` write tools. */
+    delete?(path: string): Promise<unknown>;
 }
 /**
  * The `(collectorUrl, apiKey)` pair a collector client binds to. Every consumer
@@ -26,8 +39,12 @@ export declare class CollectorError extends Error {
     constructor(message: string, status: number);
 }
 /**
- * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * Build a collector client bound to one `(collectorUrl, apiKey)` pair.
  * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ *
+ * The write methods are the narrow metadata path of #310 and nothing else:
+ * whether they are allowed at all is decided by the collector from the key's
+ * capabilities (`403` without `annotate`), not here.
  */
 export declare function createCollectorClient(config: CollectorClientConfig, fetchImpl?: typeof fetch): CollectorClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,OAAO,KAAa,GAC9B,eAAe,CAmBjB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,sEAAsE;IACtE,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,qFAAqF;IACrF,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,sEAAsE;IACtE,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,OAAO,KAAa,GAC9B,eAAe,CA6CjB"}

package/dist/client.js

@@ -11,27 +11,56 @@ function ensureTrailingSlash(url) {
     return url.endsWith("/") ? url : `${url}/`;
 }
 /**
- * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * Build a collector client bound to one `(collectorUrl, apiKey)` pair.
  * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ *
+ * The write methods are the narrow metadata path of #310 and nothing else:
+ * whether they are allowed at all is decided by the collector from the key's
+ * capabilities (`403` without `annotate`), not here.
  */
 export function createCollectorClient(config, fetchImpl = fetch) {
     const base = ensureTrailingSlash(config.collectorUrl);
+    const resolve = (path) => new URL(path.replace(/^\//, ""), base);
+    /** Send a request and turn a non-2xx response into a {@link CollectorError}. */
+    async function send(url, init) {
+        const res = await fetchImpl(url, {
+            ...init,
+            headers: { "x-api-key": config.apiKey, ...init.headers },
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new CollectorError(body || res.statusText, res.status);
+        }
+        // A successful delete answers `204 No Content`, which has no body to parse.
+        if (res.status === 204)
+            return null;
+        return res.json();
+    }
     return {
         async get(path, params = {}) {
-            const url = new URL(path.replace(/^\//, ""), base);
+            const url = resolve(path);
             for (const [key, value] of Object.entries(params)) {
                 if (value != null)
                     url.searchParams.set(key, String(value));
             }
-            const res = await fetchImpl(url, {
-                method: "GET",
-                headers: { "x-api-key": config.apiKey },
+            return send(url, { method: "GET" });
+        },
+        async post(path, body) {
+            return send(resolve(path), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
             });
-            if (!res.ok) {
-                const body = await res.text().catch(() => "");
-                throw new CollectorError(body || res.statusText, res.status);
-            }
-            return res.json();
+        },
+        async put(path, body) {
+            return send(resolve(path), {
+                method: "PUT",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+        },
+        async delete(path) {
+            return send(resolve(path), { method: "DELETE" });
         },
     };
 }

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAyBA,gEAAgE;AAChE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA6B,EAC7B,YAA0B,KAAK;IAE/B,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,SAAsB,EAAE;YAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClD,IAAI,KAAK,IAAI,IAAI;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;gBAC/B,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;aACxC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,IAAI,cAAc,CAAC,IAAI,IAAI,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/D,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}