…main

# Conflicts:
#	coderd/x/chatd/chattool/createworkspace.go

Replace the lexicographic template-ranking comparator in list_templates
with a frecency score (frequency discounted by recency), per reviewer
feedback.

- Add GetTemplateRankingSignalsByOwnerID, returning the user's recent
  active and recently-deleted workspace counts, last usage, and the count
  of distinct active developers in the org. Recently-deleted workspaces
  now contribute (recovering history the deleted=false filter discarded),
  scoped to a lookback window, and the prebuilds system user is excluded
  from the org popularity count. Replaces
  GetWorkspaceUsageGroupedByTemplateIDByOwnerID.
- Compute the affinity score in Go
  (Wp*(active + Wd*deleted)*0.5^(age/half_life) + Wo*ln(1+org_devs))
  because sqlc cannot reliably compile the parameterized decay
  expression; the query returns the raw signals. Weights, half-life, and
  lookback are explicit constants.
- Recommendation confidence is now a single score comparison: a decisive
  query match recommends on its own, otherwise the top score must clear a
  floor derived from the active-developer minimum and lead the runner-up
  by a derived margin. Stale-but-frequent usage no longer recommends.
- Replace the AsSystemRestricted call for the cross-user org count with a
  narrow dbauthz wrapper checking workspace-owner read plus a
  template-metadata read.
- Clarify list_templates/read_template guidance in the detached prompt.

Address the latest PR review feedback for frecency-based template ranking:

- Authorize template ranking signals against the exact candidate template IDs
  using the same prepared-filter semantics as GetTemplatesWithFilter, so users
  with template ACL access keep ranking signals without broad org-wide template
  read.
- Split the dbauthz mock coverage for org-scoped and any-organization calls;
  normalize duplicate subtest suffixes in the dbauthz method-test harness.
- Surface deleted-only personal usage evidence in list_templates output with a
  recently-deleted count and last-used timestamp.
- Assert the raw SQL query returns the maximum last_used_at value.
- Clarify detached prompt guidance for user_selection_required and conditional
  read_template usage.
- Document ListTemplatesOptions requirements and defaults.

Address CRF-26 by adding list_templates operation context to the user-facing
asOwner authorization error response.

Keep TestChatSystemPrompt's detached workspace awareness expectation in sync
with the updated list_templates guidance.

…atching

…truction

list_templates previously taught the model a four-value selection_hint
enum, an eleven-value recommendation_reason, per-item relevance_signals,
and a derived user_selection_required flag, re-explained in two tool
descriptions and two prompt sections. The ranked output now carries a
single fixed next_step instruction at the point of use plus an optional
recommended_template_id, and the per-item payload keeps only raw usage
evidence. Ranking, confidence thresholds, and authorization are
unchanged. Prompts reference the field through chattool.NextStepField so
they cannot drift.

Documents how agent tool calls work, including template selection and
workspace creation, in docs/ai-coder/agents/tools.

Asserts the recommendation fires for recent deleted-only personal usage
(CRF-28), adds the both-above-floor-with-large-gap recommendation case
(CRF-29), and rewords the affinity-score comments to drop the inaccurate
sqlc fragility claim; the score lives in Go so the ranking policy and its
confidence thresholds stay in one place.

Shows a concrete query and ranked two-template response in the agent
tools doc, and clarifies that templates are scored independently with
only raw evidence fields returned.

# Conflicts:
#	coderd/x/chatd/chatd_test.go

Add observability for the list_templates ranking decision and its
downstream acceptance.

Tier 1: a structured decision log per call with correlation IDs,
ranking inputs (scores, gap, thresholds), outcome, and reason. The
raw query text is never logged, only its presence and length.

Tier 2: Prometheus metrics for recommendation outcome, signal-load
failures, and the affinity gap between the top two candidates.

Tier 3: an in-memory, best-effort RecommendationTracker correlates a
recommendation with the template create_workspace later builds,
recorded as template_recommendation_followup_total plus a log.

The affinity score stays internal to the response; the telemetry
surfaces it in logs and metrics without exposing it to the model.

Regenerates the Prometheus metrics docs for the new metrics.

- Reword recordListTemplatesTelemetry doc: the affinity score is "not
  included in the tool result shown to the model" rather than "stays
  internal", which misread as not logged (CRF-13).
- Drop the redundant "list_templates ranking telemetry" section heading
  in the Metrics struct; the field names already convey it (CRF-14).
- Document the intentional query-tie recommendation rationale: a query
  match is the baseline confidence signal there, so affinity only breaks
  the tie and need not clear the no-query affinity floor (Codex P2).