whose-turn 1.0.0-alpha.6 → 1.0.0-alpha.8

package/lib/api.mjs

@@ -4,9 +4,9 @@ import { join } from 'node:path';
 import { createStatic } from './static.mjs';
 import { ApiError, toApiError } from './errors.mjs';
 import { connectorCatalogue, secretTarget, secretsRequired } from '../connectors/index.mjs';
-import { entryShapeViolations, normaliseWorkspaces, WORKSPACE_FIELDS } from './config.mjs';
+import { desktopOf, entryShapeViolations, normaliseWorkspaces, WORKSPACE_FIELDS } from './config.mjs';
 import { FACTS } from './facts.mjs';
-import { createFeedback, isConfigured } from './feedback.mjs';
+import { createFeedback, installOf } from './feedback.mjs';
 import { composeIssue, DEFAULT_COMPOSER } from './compose.mjs';
 import { readSize, saveSize, checkMode, spawnOpener } from './window.mjs';
 import { frameHandOff } from './handoff.mjs';
@@ -66,6 +66,15 @@ const marksProblem = (body) => {
   if ('base' in body && !(Number.isFinite(body.base) && body.base <= Date.now() + CLOCK_SKEW_MS)) {
     return 'base must be a number of milliseconds, not in the future';
   }
+  if (body.notes !== undefined) {
+    if (!body.notes || typeof body.notes !== 'object' || Array.isArray(body.notes)) {
+      return 'notes must map row ids to a line of text';
+    }
+    const wrongNote = Object.entries(body.notes).find(([, value]) => typeof value !== 'string' || value.length > 200);
+    if (wrongNote) {
+      return `notes.${wrongNote[0]} must be text of at most 200 characters`;
+    }
+  }
   if (body.handled === undefined) {
     return '';
   }
@@ -100,9 +109,8 @@ const aggregateSummary = (workspaces) => {
 
 const OPEN_COOLDOWN_MS = 5000;
 
-export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir, opener = spawnOpener(appDir), updater = noUpdates() }) => {
+export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir, opener = spawnOpener(appDir), updater = noUpdates(), changelog = null, version = '' }) => {
   const windowFile = createStatic(join(appDir, 'dist'));
-  const feedbackCache = {};
   const pick = (id) => {
     const workspaces = registry.workspaces;
     if (!workspaces.length) {
@@ -155,14 +163,20 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
         return send(response, 200, { workspaces: [], problems: registry.problems, update: updater.status() });
       }
       const workspace = pick(url.searchParams.get('ws'));
-      return send(response, 200, { ...workspace.snapshot(url.searchParams.get('full') === '1'), workspaces: registry.workspaces.map((item) => item.describe()), problems: registry.problems, update: updater.status() });
+      return send(response, 200, { ...workspace.snapshot(url.searchParams.get('full') === '1'), workspaces: registry.workspaces.map((item) => item.describe()), problems: registry.problems, notifications: registry.notifications, update: updater.status() });
     }
     if (url.pathname === '/api/summary') {
-      return send(response, 200, { ...aggregateSummary(registry.workspaces), problems: registry.problems, handed: inbox.pending().length, update: updater.status() });
+      return send(response, 200, { ...aggregateSummary(registry.workspaces), problems: registry.problems, handed: inbox.pending().length, notifications: registry.notifications, update: updater.status() });
     }
     if (url.pathname === '/api/config') {
       const tables = Object.fromEntries(registry.workspaces.map((workspace) => [workspace.id, workspace.rulesTable]));
-      return send(response, 200, { workspaces: registry.rawWorkspaces, problems: registry.problems, connectors: connectorCatalogue(), fields: WORKSPACE_FIELDS, facts: FACTS, tables, table_warnings: normaliseWorkspaces(registry.rawWorkspaces).warnings, config_file: registry.configFile });
+      return send(response, 200, { workspaces: registry.rawWorkspaces, notifications: registry.notifications, problems: registry.problems, connectors: connectorCatalogue(), fields: WORKSPACE_FIELDS, facts: FACTS, tables, table_warnings: normaliseWorkspaces(registry.rawWorkspaces).warnings, config_file: registry.configFile });
+    }
+    if (url.pathname === '/api/changelog') {
+      if (!changelog) {
+        throw new ApiError('CHANGELOG_UNAVAILABLE');
+      }
+      return send(response, 200, changelog);
     }
     if (url.pathname === '/api/inbox') {
       return send(response, 200, { items: inbox.pending(url.searchParams.get('consumer') || '') });
@@ -170,10 +184,10 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     if (url.pathname === '/api/feedback') {
       const id = url.searchParams.get('id');
       if (id) {
-        return send(response, 200, { report: await reports.detail(reportDeps(), id) });
+        return send(response, 200, { report: await reports.detail(id) });
       }
-      const list = await reports.states(reportDeps());
-      return send(response, 200, { configured: isConfigured(registry.feedback), project: registry.feedback ? registry.feedback.project : '', reports: list });
+      const list = await reports.states();
+      return send(response, 200, { reports: list });
     }
     if (url.pathname === '/api/handoff') {
       if (url.searchParams.get('all') === '1') {
@@ -225,6 +239,15 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     return { ...target, value: String(item.value).trim() };
   });
 
+  const handleNotifications = async (body) => {
+    const desktop = desktopOf(body);
+    if (desktop === undefined) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'desktop must be true or false' }, [{ field: 'desktop', description: 'Send {desktop: true} or {desktop: false}.' }]);
+    }
+    await registry.saveNotifications({ desktop });
+    return { notifications: registry.notifications };
+  };
+
   const handleConfig = async (body) => {
     if (!Array.isArray(body.workspaces)) {
       throw new ApiError('INVALID_ARGUMENT', { detail: 'workspaces must be a list' });
@@ -260,7 +283,7 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
       await secrets.set(secret.service, secret.account, secret.value);
     }
     await saveConfig(body.workspaces);
-    return { workspaces: registry.workspaces.map((workspace) => workspace.describe()), problems: registry.problems, secrets_stored: stored.map(({ service, account }) => ({ service, account })) };
+    return { workspaces: registry.workspaces.map((workspace) => workspace.describe()), notifications: registry.notifications, problems: registry.problems, secrets_stored: stored.map(({ service, account }) => ({ service, account })) };
   };
 
   const handleSecret = async (body) => {
@@ -306,12 +329,10 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     return { item: inbox.add({ ws: workspace.id, ws_name: workspace.name, kind, ref, snapshot }) };
   };
 
-  const reportDeps = () => ({ settings: registry.feedback, secrets, http });
-
   let lastRemark = { text: '', at: 0 };
   const handleFeedback = async (body) => {
-    if (!isConfigured(registry.feedback)) {
-      throw new ApiError('NOT_CONFIGURED');
+    if ('context' in body) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'context is no longer accepted: a report carries only its text and the monitor version' }, [{ field: 'context', description: 'Remove it; nothing but what the user wrote leaves this machine.' }]);
     }
     const remark = typeof body.text === 'string' ? body.text.trim() : '';
     if (!remark && !String(body.title || '').trim()) {
@@ -323,16 +344,12 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     if (remark) {
       lastRemark = { text: remark, at: Date.now() };
     }
-    let context = null;
-    if (body.ws && body.kind_ref) {
-      const workspace = pick(body.ws);
-      context = workspace.handOffText(body.kind_ref.kind, body.kind_ref.ref);
-    }
+    const sources = (body.ws ? [pick(body.ws)] : registry.workspaces).flatMap((workspace) => workspace.sourceTypes);
     try {
       const composer = registry.feedback && registry.feedback.composer && registry.feedback.composer.command ? registry.feedback.composer : DEFAULT_COMPOSER;
-      const shaped = remark ? await composeIssue(remark, { about: context || '', composer, bugWords: registry.feedback && registry.feedback.bug_words }) : { kind: body.kind, title: body.title, body: body.body, composed_by: body.from || 'caller' };
-      const issue = await createFeedback({ settings: registry.feedback, secrets, http, cache: feedbackCache, reports }, { kind: shaped.kind, title: shaped.title, body: shaped.body, from: body.from, context: context || body.context || null });
-      return { issue, composed_by: shaped.composed_by, reports: await reports.states(reportDeps()) };
+      const shaped = remark ? await composeIssue(remark, { composer, bugWords: registry.feedback && registry.feedback.bug_words }) : { kind: body.kind, title: body.title, body: body.body, composed_by: body.from || 'caller' };
+      const issue = await createFeedback({ http, reports, relayUrl: reports.relayUrl, version, sources, install: installOf(appDir), client: body.client }, { kind: shaped.kind, title: shaped.title, body: shaped.body });
+      return { issue, composed_by: shaped.composed_by, reports: await reports.states() };
     } catch (error) {
       lastRemark = { text: '', at: 0 };
       throw error;
@@ -352,6 +369,9 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     if (url.pathname === '/api/config') {
       return send(response, 200, await handleConfig(body));
     }
+    if (url.pathname === '/api/notifications') {
+      return send(response, 200, await handleNotifications(body));
+    }
     if (url.pathname === '/api/secrets') {
       return send(response, 200, await handleSecret(body));
     }

package/lib/changelog.mjs

@@ -0,0 +1,74 @@
+/** Parses CHANGELOG.md (Keep a Changelog) into versions, newest first as written, and reads it next to server.mjs. */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VERSION_HEADING = /^##\s+\[([^\]]+)\](?:\s+-\s+(\S.*?))?\s*$/;
+const SECTION_HEADING = /^###\s+(\S.*?)\s*$/;
+const ISSUE_ID = String.raw`[A-Z][A-Z0-9]+-\d+`;
+const TRAILING_IDS = new RegExp(String.raw`(?<=[.!?])\s+${ISSUE_ID}(?:,\s*${ISSUE_ID})*\.?$`);
+const BRACKETED_IDS = new RegExp(String.raw`\s*\((?:${ISSUE_ID})(?:,\s*${ISSUE_ID})*\)`, 'g');
+
+/** An entry as a user reads it: the internal tracker ids at its end or in brackets are dropped. */
+export const withoutIds = (entry) => entry.replace(BRACKETED_IDS, '').replace(TRAILING_IDS, '').trim();
+
+/** [{version, date, sections: [{kind, items: [markdown]}]}]; a malformed `##` heading ends the version above it and its body is dropped. */
+export const parseChangelog = (text) => {
+  const versions = [];
+  let version = null;
+  let section = null;
+  let item = null;
+  const closeItem = () => {
+    if (item !== null && section) {
+      section.items.push(withoutIds(item.trim()));
+    }
+    item = null;
+  };
+  for (const line of String(text).split(/\r?\n/)) {
+    if (line.startsWith('## ') || line === '##') {
+      closeItem();
+      const heading = line.match(VERSION_HEADING);
+      version = heading ? { version: heading[1], date: heading[2] || '', sections: [] } : null;
+      section = null;
+      if (version) {
+        versions.push(version);
+      }
+      continue;
+    }
+    if (!version) {
+      continue;
+    }
+    const kind = line.match(SECTION_HEADING);
+    if (kind) {
+      closeItem();
+      section = { kind: kind[1], items: [] };
+      version.sections.push(section);
+      continue;
+    }
+    if (!section) {
+      continue;
+    }
+    if (line.startsWith('- ')) {
+      closeItem();
+      item = line.slice(2);
+    } else if (item !== null && /^\s+\S/.test(line)) {
+      item += '\n' + line.trim();
+    } else {
+      closeItem();
+    }
+  }
+  closeItem();
+  versions.forEach((entry) => {
+    entry.sections = entry.sections.filter((one) => one.items.length);
+  });
+  return versions;
+};
+
+/** The reply of GET /api/changelog: the released versions only, or null when the file cannot be read. */
+export const loadChangelog = (appDir, current) => {
+  try {
+    const versions = parseChangelog(readFileSync(join(appDir, 'CHANGELOG.md'), 'utf8'));
+    return { current, versions: versions.filter((entry) => entry.version !== 'Unreleased') };
+  } catch {
+    return null;
+  }
+};

package/lib/compose.mjs

@@ -1,17 +1,15 @@
 /** Turns a remark into an issue (title, kind, body) with the user's own agent CLI, `claude -p` unless the config names another; falls back to the first line as the title. RMA-109. */
 import { execFile } from 'node:child_process';
 import { escapeRegex } from './text.mjs';
-import { untrustedBlock } from './handoff.mjs';
 
 const KINDS = ['bug', 'improvement', 'idea'];
 export const DEFAULT_COMPOSER = { command: 'claude', args: ['-p', '--output-format', 'json', '--model', 'claude-haiku-5-5'] };
 
-const PROMPT = (text, about) => `You turn a user's remark about a tool called Whose Turn (a local monitor of tickets and pull requests) into an issue for its backlog.
+const PROMPT = (text) => `You turn a user's remark about a tool called Whose Turn (a local monitor of tickets and pull requests) into an issue for its backlog.
 Answer with one JSON object only, no prose, no code fence: {"title": string, "kind": "bug" | "improvement" | "idea", "body": string}.
-Rules: the title and the body are in English whatever language the remark is in; translate faithfully, keep every detail the user gave, add nothing the user did not say. The title is one line under 80 characters; kind is bug when something misbehaves, improvement when something that exists should be better, idea when it is new; the body restates the remark clearly and may end with one line "Context: …" taken from the context below if it helps a developer find the place, and, when the remark was not in English, with one line "Original: …" quoting it as written.
+Rules: the title and the body are in English whatever language the remark is in; translate faithfully, keep every detail the user gave, add nothing the user did not say. The title is one line under 80 characters; kind is bug when something misbehaves, improvement when something that exists should be better, idea when it is new; the body restates the remark clearly and ends, when the remark was not in English, with one line "Original: …" quoting it as written.
 Remark:
-${text}
-${about ? `\nContext of the window at that moment:\n${untrustedBlock(about.slice(0, 3000))}` : ''}`;
+${text}`;
 
 const DEFAULT_BUG_WORDS = ['bug', 'broken', 'crash', 'error', 'fail', 'wrong'];
 const fallback = (text, bugWords) => {
@@ -50,8 +48,8 @@ const runCommand = (composer) => (prompt, timeoutMs) => new Promise((resolve, re
   child.stdin.end(prompt);
 });
 
-/** @param {string} text @param {{ about?: string, composer?: object, bugWords?: string[], run?: Function, timeoutMs?: number }} [options] */
-export const composeIssue = async (text, { about = '', composer = DEFAULT_COMPOSER, bugWords = [], run, timeoutMs = 45000 } = {}) => {
+/** @param {string} text @param {{ composer?: object, bugWords?: string[], run?: Function, timeoutMs?: number }} [options] */
+export const composeIssue = async (text, { composer = DEFAULT_COMPOSER, bugWords = [], run, timeoutMs = 45000 } = {}) => {
   const clean = String(text || '').trim();
   if (!clean) {
     throw new Error('Write at least one line');
@@ -60,7 +58,7 @@ export const composeIssue = async (text, { about = '', composer = DEFAULT_COMPOS
   const model = args[args.indexOf('--model') + 1];
   const label = composer.label || (args.includes('--model') && model ? `${composer.command} ${model}` : composer.command);
   try {
-    return parse(await (run || runCommand(composer))(PROMPT(clean, about), timeoutMs), label);
+    return parse(await (run || runCommand(composer))(PROMPT(clean), timeoutMs), label);
   } catch {
     return fallback(clean, bugWords);
   }

package/lib/config.mjs

@@ -2,6 +2,7 @@
 import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+import { isObject } from './text.mjs';
 import { isHex, derivedSeeds } from './palette.mjs';
 import { statusGroups } from './facts.mjs';
 import { tableProblems, tableWarnings } from './table.mjs';
@@ -115,8 +116,6 @@ const legacyWorkspace = (raw) => {
   return { id: 'default', name: 'Default', connectors, rules: raw.rules, key_pattern: raw.jira?.key_pattern };
 };
 
-const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-
 const connectorEntries = (connectors) => {
   const list = Array.isArray(connectors) ? connectors : Object.entries(connectors || {}).map(([type, settings]) => ({ type, ...settings }));
   return list.filter(isObject).map((entry) => ({ ...entry, id: String(entry.id || entry.type) }));
@@ -243,7 +242,8 @@ export const loadConfig = (env = process.env) => {
     pollSeconds: Number(source.poll_seconds || 60),
     historyDays: Number(source.history_days || 14),
     health: normaliseHealth(source, problems),
-    feedback: source.feedback && typeof source.feedback === 'object' ? source.feedback : null,
+    feedback: withoutRetiredFeedbackKeys(source.feedback),
+    notifications: normaliseNotifications(source.notifications, problems),
     workspaces,
     rawWorkspaces,
     problems: [...problems, ...shapeProblems, ...warningLines],
@@ -259,6 +259,20 @@ const normaliseHealth = (source, problems) => Object.fromEntries(Object.entries(
   return [key, value];
 }));
 
+/** The boolean `desktop` of a notifications block, or undefined. */
+export const desktopOf = (notifications) => (isObject(notifications) && typeof notifications.desktop === 'boolean' ? notifications.desktop : undefined);
+
+const normaliseNotifications = (notifications, problems) => {
+  if (notifications === undefined) {
+    return { desktop: true };
+  }
+  const desktop = desktopOf(notifications);
+  if (desktop === undefined) {
+    problems.push('notifications.desktop must be true or false; desktop notifications stay on.');
+  }
+  return { desktop: desktop ?? true };
+};
+
 /** Field violations for entries that are not objects: a workspace, or a connector in a workspace's connectors list. Checked before normalising, which assumes objects. */
 export const entryShapeViolations = (rawWorkspaces) => (Array.isArray(rawWorkspaces) ? rawWorkspaces : []).flatMap((workspace, index) => {
   if (!isObject(workspace)) {
@@ -297,14 +311,33 @@ export const normaliseWorkspaces = (rawWorkspaces) => {
   return { workspaces, problems: violations.map((entry) => entry.description), violations, warnings };
 };
 
-/** Writes the workspace list into the config file, keeping its other top-level keys and dropping the flat pre-workspace keys; the previous file is kept as config.json.bak. */
+const RETIRED_FEEDBACK_KEYS = ['workspace', 'team', 'project', 'token_service', 'assign'];
+
+const withoutRetiredFeedbackKeys = (feedback) => (isObject(feedback) ? Object.fromEntries(Object.entries(feedback).filter(([key]) => !RETIRED_FEEDBACK_KEYS.includes(key))) : {});
+
+/** Writes the workspace list into the config file; the previous file stays as config.json.bak. */
 export const saveWorkspaces = (configFile, rawWorkspaces) => {
   const current = readJson(configFile);
   const source = current && !current.parse_error ? current : {};
   delete source.github;
   delete source.jira;
   delete source.rules;
-  const next = { ...source, workspaces: rawWorkspaces };
+  const feedback = withoutRetiredFeedbackKeys(source.feedback);
+  if (Object.keys(feedback).length) {
+    source.feedback = feedback;
+  } else {
+    delete source.feedback;
+  }
+  writeConfig(configFile, { ...source, workspaces: rawWorkspaces });
+};
+
+/** Writes the validated notifications block into the config file. */
+export const saveNotifications = (configFile, notifications) => {
+  const current = readJson(configFile);
+  writeConfig(configFile, { ...(current && !current.parse_error ? current : {}), notifications });
+};
+
+const writeConfig = (configFile, next) => {
   mkdirSync(dirname(configFile), { recursive: true });
   if (existsSync(configFile)) {
     writeFileSync(`${configFile}.bak.tmp`, readFileSync(configFile));

package/lib/errors.mjs

@@ -10,12 +10,12 @@ const REASONS = {
   INVALID_ARGUMENT: { code: 400, status: 'INVALID_ARGUMENT', message: 'A required value is missing or has the wrong shape.' },
   INVALID_CONFIG: { code: 400, status: 'INVALID_ARGUMENT', message: 'The workspace list has problems; nothing was saved.' },
   NO_WORKSPACE: { code: 412, status: 'FAILED_PRECONDITION', message: 'No workspace is configured; open Settings to add one.' },
-  NOT_CONFIGURED: { code: 412, status: 'FAILED_PRECONDITION', message: 'Feedback is not configured: set feedback.workspace, feedback.team and feedback.project in the config.' },
   UPSTREAM_FAILED: { code: 502, status: 'UNAVAILABLE', message: 'The tracker did not answer; try again in a minute.' },
   RATE_LIMITED: { code: 429, status: 'RESOURCE_EXHAUSTED', message: 'The source is rate-limited; try again later.' },
   OPEN_TOO_SOON: { code: 429, status: 'RESOURCE_EXHAUSTED', message: 'The window was just opened; wait a few seconds before opening it again.' },
   UPDATE_IN_PROGRESS: { code: 409, status: 'ABORTED', message: 'An update is already installing; the server restarts when it is done.' },
   UPDATE_UNAVAILABLE: { code: 412, status: 'FAILED_PRECONDITION', message: 'There is no update to apply: the server runs from a checkout or already runs the latest version.' },
+  CHANGELOG_UNAVAILABLE: { code: 404, status: 'NOT_FOUND', message: 'This install has no readable CHANGELOG.md.' },
   FORBIDDEN_ORIGIN: { code: 403, status: 'PERMISSION_DENIED', message: 'Only the local window may call this API.' },
   INTERNAL: { code: 500, status: 'INTERNAL', message: 'The local server failed on this request; the details are in its log.' },
 };

package/lib/facts.mjs

@@ -6,32 +6,33 @@ export const shortDate = (iso) => new Date(iso).toLocaleDateString('en-US', { mo
 const CATEGORY_GROUPS = { new: 'todo', indeterminate: 'in_progress', done: 'done' };
 const CHAIN_GROUPS = ['backlog', 'passed', 'code_review', 'qa', 'on_hold'];
 
-/** Every fact a table row may test or quote: its type, the closed values when there are any, and where it comes from. */
+/** The closed fact dictionary a table row may test or quote, each with its plain words.
+ * Rules: docs/mechanisms/rules-table.md, Facts. */
 export const FACTS = {
-  connector: { type: 'string', from: 'the connector entry id the ticket came from' },
-  'ticket.key': { type: 'string', from: 'tracker connectors (jira, linear)' },
-  'ticket.status': { type: 'string', values: 'status groups', from: 'the ticket status matched against rules.statuses; else todo, in_progress or done from the status category' },
-  'ticket.status_name': { type: 'string', from: 'the status as the tracker names it' },
-  'ticket.assignee': { type: 'string', from: '"me" when the ticket is on you, else the assignee name' },
-  'ticket.done': { type: 'boolean', from: 'the status category is done' },
-  'ticket.started': { type: 'boolean', from: 'the status category is in progress' },
-  'ticket.hold_reason': { type: 'string', from: 'the comment that explains an on_hold status; missing when none does' },
-  'pr.open': { type: 'boolean', from: 'github: the ticket has an open PR; false when it has none' },
-  'pr.merged': { type: 'boolean', from: 'github: the ticket PR is merged; false when it has none' },
-  'pr.number': { type: 'number', from: 'github' },
-  'pr.checks': { type: 'string', values: ['passing', 'failing', 'running', 'none'], from: 'github' },
-  'pr.review': { type: 'string', values: ['approved', 'changes_requested', 'none'], from: 'github' },
-  'pr.base': { type: 'string', from: 'github: the branch the PR goes into' },
-  'pr.unanswered': { type: 'boolean', from: 'github: a human commented after your last comment and it is not an approval' },
-  'pr.commenter': { type: 'string', from: 'github: the author of that last comment' },
-  'comment.mentions_me': { type: 'boolean', from: 'tracker comments: an unanswered @-mention of you on the ticket' },
-  'comment.is_question': { type: 'boolean', from: 'the newest unanswered mention reads as a question' },
-  'comment.author': { type: 'string', from: 'the author of the newest unanswered mention' },
-  unanswered_count: { type: 'number', from: 'how many @-mentions of you on the ticket are unanswered' },
-  'run.failed': { type: 'boolean', from: 'github: the latest completed run of a workflow on the default branch failed; missing on tickets' },
-  'run.workflow': { type: 'string', from: 'github: the name of that workflow' },
-  'run.branch': { type: 'string', from: 'github: the branch it ran on, the default branch' },
-  'run.mine': { type: 'boolean', from: 'github: you pushed the commit or started the run' },
+  connector: { type: 'string', name: 'the source', from: 'the connector entry id the ticket came from' },
+  'ticket.key': { type: 'string', name: 'the ticket key', from: 'tracker connectors (jira, linear)' },
+  'ticket.status': { type: 'string', name: 'the ticket status', values: 'status groups', from: 'the ticket status matched against rules.statuses; else todo, in_progress or done from the status category' },
+  'ticket.status_name': { type: 'string', name: 'the status', from: 'the status as the tracker names it' },
+  'ticket.assignee': { type: 'string', name: 'the assignee', from: '"me" when the ticket is on you, else the assignee name' },
+  'ticket.done': { type: 'boolean', says: ['the ticket is done', 'the ticket is not done'], from: 'the status category is done' },
+  'ticket.started': { type: 'boolean', says: ['the ticket is started', 'the ticket is not started'], from: 'the status category is in progress' },
+  'ticket.hold_reason': { type: 'string', name: 'the hold reason', from: 'the comment that explains an on_hold status; missing when none does' },
+  'pr.open': { type: 'boolean', says: ['the PR is open', 'no PR is open'], from: 'github: the ticket has an open PR; false when it has none' },
+  'pr.merged': { type: 'boolean', says: ['the PR is merged', 'the PR is not merged'], from: 'github: the ticket PR is merged; false when it has none' },
+  'pr.number': { type: 'number', name: 'the PR number', from: 'github' },
+  'pr.checks': { type: 'string', name: 'the PR checks', values: ['passing', 'failing', 'running', 'none'], from: 'github' },
+  'pr.review': { type: 'string', name: 'the PR review', values: ['approved', 'changes_requested', 'none'], from: 'github' },
+  'pr.base': { type: 'string', name: 'the target branch', from: 'github: the branch the PR goes into' },
+  'pr.unanswered': { type: 'boolean', says: ['a comment on the PR waits for your answer', 'no comment on the PR waits for your answer'], from: 'github: a human commented after your last comment and it is not an approval' },
+  'pr.commenter': { type: 'string', name: 'the commenter', from: 'github: the author of that last comment' },
+  'comment.mentions_me': { type: 'boolean', says: ['you are mentioned and have not answered', 'no mention of you waits for an answer'], from: 'tracker comments: an unanswered @-mention of you on the ticket' },
+  'comment.is_question': { type: 'boolean', says: ['the mention is a question', 'the mention is not a question'], from: 'the newest unanswered mention reads as a question' },
+  'comment.author': { type: 'string', name: 'the author', from: 'the author of the newest unanswered mention' },
+  unanswered_count: { type: 'number', name: 'the number of mentions of you', from: 'how many @-mentions of you on the ticket are unanswered' },
+  'run.failed': { type: 'boolean', says: ['a workflow run failed', 'no workflow run failed'], from: 'github: the latest completed run of a workflow on the default branch failed; missing on tickets' },
+  'run.workflow': { type: 'string', name: 'the workflow', from: 'github: the name of that workflow' },
+  'run.branch': { type: 'string', name: 'the branch', from: 'github: the branch it ran on, the default branch' },
+  'run.mine': { type: 'boolean', says: ['the run is yours', 'the run is not yours'], from: 'github: you pushed the commit or started the run' },
 };
 
 /** The order status words are tried in: the chain's groups first, then any extra group in rules.statuses. */