@skillcdn/console 0.1.9 → 0.1.11

package/src/router.ts

@@ -1,10 +1,12 @@
 import { isFolderPath, isSignInFailure, SIGN_IN_PARAM, type SignInFailure } from "./api.js";
+import { isMonth } from "./dates.js";
 
 // The addresses of the default console (ADR-0010): the router is a function from a URL to a
 // route, and the hrefs below are its inverse. A project's pages live under `/projects/<key>`,
 // the word the REST API uses; an address names what it shows (a task by its number, a decision
-// by its id, a document by its path), every form has one, and the query says how a page is
-// shown (`?edit`, `?ask`, `?new`, `?version=`, `?q=`). The old addresses are taken to the new.
+// by its id, a document by its path, a goal by its id), every form has one, and the query says
+// how a page is shown (`?edit`, `?ask`, `?new`, `?version=`, `?q=`, `?month=`, and the board's
+// filters). The old addresses are taken to the new.
 
 /** How a task's page is shown: as it is, or with one of its forms open. */
 export type TaskFormKind = "edit" | "ask";
@@ -16,10 +18,22 @@ export type DocsView =
   | { readonly kind: "edit" }
   | { readonly kind: "search"; readonly q: string };
 
+/**
+ * What the board is narrowed to (ADR-0019), from the query: a category by its key (`""` for
+ * the tasks with none), a goal by its id (`""` for the tasks with none), a person by their id,
+ * or the person's own.
+ */
+export interface BoardFilter {
+  readonly category?: string | undefined;
+  readonly goal?: string | undefined;
+  readonly person?: string | undefined;
+  readonly mine?: boolean | undefined;
+}
+
 export type Route =
   | { readonly name: "projects" }
   | { readonly name: "new-project" }
-  | { readonly name: "board"; readonly project: string }
+  | { readonly name: "board"; readonly project: string; readonly filter: BoardFilter }
   | { readonly name: "new-task"; readonly project: string }
   | {
       readonly name: "task";
@@ -38,6 +52,21 @@ export type Route =
   | { readonly name: "decisions"; readonly project: string }
   | { readonly name: "new-decision"; readonly project: string }
   | { readonly name: "decision"; readonly project: string; readonly id: string }
+  /** The calendar of a project: the month shown, or this one when the address names none, narrowed as the board is. */
+  | {
+      readonly name: "calendar";
+      readonly project: string;
+      readonly month: string | undefined;
+      readonly filter: BoardFilter;
+    }
+  | { readonly name: "roadmap"; readonly project: string }
+  | { readonly name: "new-goal"; readonly project: string }
+  | {
+      readonly name: "goal";
+      readonly project: string;
+      readonly id: string;
+      readonly form: "edit" | undefined;
+    }
   | { readonly name: "feed"; readonly project: string }
   | { readonly name: "skills"; readonly project: string }
   | { readonly name: "members"; readonly project: string }
@@ -47,6 +76,10 @@ export type Route =
   | { readonly name: "person-agents"; readonly id: string }
   | { readonly name: "agents" }
   | { readonly name: "new-token" }
+  /** What is on the person's plate across their projects. */
+  | { readonly name: "work" }
+  /** The categories tasks are sorted into; an administrator keeps them here. */
+  | { readonly name: "categories" }
   /** Where a person approves an agent's connection, by the code it showed, or types one. */
   | { readonly name: "connect"; readonly code: string | undefined }
   /** An address that moved: the page takes the person to `to` in its place. */
@@ -54,7 +87,15 @@ export type Route =
   | { readonly name: "not-found" };
 
 /** The pages of a project, after its key. */
-export type ProjectPage = "docs" | "decisions" | "feed" | "skills" | "members" | "settings";
+export type ProjectPage =
+  | "docs"
+  | "decisions"
+  | "calendar"
+  | "roadmap"
+  | "feed"
+  | "skills"
+  | "members"
+  | "settings";
 
 export const PATHS = {
   /** The projects the person may see: the front page. */
@@ -62,11 +103,15 @@ export const PATHS = {
   /** Where a project's pages are: `/projects/<key>`, then the page. */
   project: "/projects",
   newProject: "/projects/new",
+  /** What is on the person's plate, across the projects they may see. */
+  work: "/work",
   people: "/people",
   /** The agents of whoever is signed in, which hold their tokens: their own page. */
   agents: "/agents",
   /** The form for a token made by hand, for a script or a console of one's own. */
   newToken: "/agents/new",
+  /** The categories tasks are sorted into, kept by an administrator. */
+  categories: "/categories",
   /** Where an agent's connection is approved (ADR-0011): `/connect/<code>`, or the code typed. */
   connect: "/connect",
 } as const;
@@ -77,7 +122,7 @@ const NUMBER = /^[1-9][0-9]{0,8}$/;
 /** A code as it may be typed into an address: checked for what it is by the page. */
 const CODE_TEXT = /^[A-Za-z0-9-]{1,16}$/;
 /** The pages of a project that take nothing after their name. */
-const PLAIN_PAGES: readonly Exclude<ProjectPage, "docs">[] = [
+const PLAIN_PAGES: readonly Exclude<ProjectPage, "docs" | "calendar" | "roadmap">[] = [
   "decisions",
   "feed",
   "skills",
@@ -103,6 +148,19 @@ export function movedFrom(pathname: string): string | undefined {
 const taskFormOf = (params: URLSearchParams): TaskFormKind | undefined =>
   params.has("edit") ? "edit" : params.has("ask") ? "ask" : undefined;
 
+/** The board's filters, as the query names them; a value that is not one is left out. */
+const boardFilterOf = (params: URLSearchParams): BoardFilter => {
+  const category = params.get("category");
+  const goal = params.get("goal");
+  const person = params.get("person");
+  return {
+    ...(category !== null && (category === "" || PROJECT_KEY.test(category)) ? { category } : {}),
+    ...(goal !== null && (goal === "" || UUID.test(goal)) ? { goal } : {}),
+    ...(person !== null && UUID.test(person) ? { person } : {}),
+    ...(params.has("mine") ? { mine: true } : {}),
+  };
+};
+
 /** The view the query asks for at a path, or nothing for one the path cannot be shown as. */
 const docsViewOf = (params: URLSearchParams, path: string): DocsView | undefined => {
   const q = params.get("q");
@@ -137,6 +195,9 @@ export function matchRoute(pathname: string, search = ""): Route {
   if (path === PATHS.newProject) {
     return { name: "new-project" };
   }
+  if (path === PATHS.work) {
+    return { name: "work" };
+  }
   if (path === PATHS.people) {
     return { name: "people" };
   }
@@ -146,6 +207,9 @@ export function matchRoute(pathname: string, search = ""): Route {
   if (path === PATHS.newToken) {
     return { name: "new-token" };
   }
+  if (path === PATHS.categories) {
+    return { name: "categories" };
+  }
   if (path === PATHS.connect) {
     return { name: "connect", code: undefined };
   }
@@ -167,7 +231,7 @@ export function matchRoute(pathname: string, search = ""): Route {
     return NOT_FOUND;
   }
   if (page === undefined) {
-    return { name: "board", project };
+    return { name: "board", project, filter: boardFilterOf(params) };
   }
   if (page === "docs") {
     // The rest of the path is the document's, or a folder's, or nothing for the root.
@@ -205,9 +269,27 @@ export function matchRoute(pathname: string, search = ""): Route {
     }
     return UUID.test(third) ? { name: "decision", project, id: third } : NOT_FOUND;
   }
+  if (page === "roadmap" && third !== undefined) {
+    if (third === "new") {
+      return { name: "new-goal", project };
+    }
+    return UUID.test(third)
+      ? { name: "goal", project, id: third, form: params.has("edit") ? "edit" : undefined }
+      : NOT_FOUND;
+  }
   if (third !== undefined) {
     return NOT_FOUND;
   }
+  if (page === "calendar") {
+    const month = params.get("month");
+    if (month !== null && !isMonth(month)) {
+      return NOT_FOUND;
+    }
+    return { name: "calendar", project, month: month ?? undefined, filter: boardFilterOf(params) };
+  }
+  if (page === "roadmap") {
+    return { name: "roadmap", project };
+  }
   const found = PLAIN_PAGES.find((candidate) => candidate === page);
   return found === undefined ? NOT_FOUND : { name: found, project };
 }
@@ -228,6 +310,31 @@ export function projectHref(key: string, page?: ProjectPage): string {
   return page === undefined ? base : `${base}/${page}`;
 }
 
+/** Where a project's board is, narrowed as the filter says; the plain board for an empty one. */
+export function boardHref(key: string, filter: BoardFilter = {}): string {
+  const parts = filterParts(filter);
+  return parts.length === 0 ? projectHref(key) : `${projectHref(key)}?${parts.join("&")}`;
+}
+
+/** The filter as the query carries it, a part per narrowing; nothing for the plain board. */
+function filterParts(filter: BoardFilter): string[] {
+  const parts: string[] = [];
+  // An empty value means "none": it keeps its sign; "mine" is a flag and has no value.
+  if (filter.category !== undefined) {
+    parts.push(`category=${encodeURIComponent(filter.category)}`);
+  }
+  if (filter.goal !== undefined) {
+    parts.push(`goal=${encodeURIComponent(filter.goal)}`);
+  }
+  if (filter.person !== undefined) {
+    parts.push(`person=${encodeURIComponent(filter.person)}`);
+  }
+  if (filter.mine === true) {
+    parts.push("mine");
+  }
+  return parts;
+}
+
 /** Where a task is written: the form. */
 export function newTaskHref(key: string): string {
   return `${PATHS.project}/${key}/tasks/new`;
@@ -249,6 +356,24 @@ export function decisionHref(key: string, id: string): string {
   return `${PATHS.project}/${key}/decisions/${id}`;
 }
 
+/** Where a project's calendar is, on a month, or on this one when none is named, narrowed as the filter says. */
+export function calendarHref(key: string, month?: string, filter: BoardFilter = {}): string {
+  const base = projectHref(key, "calendar");
+  const parts = [...(month === undefined ? [] : [`month=${month}`]), ...filterParts(filter)];
+  return parts.length === 0 ? base : `${base}?${parts.join("&")}`;
+}
+
+/** Where a goal is set: the form. */
+export function newGoalHref(key: string): string {
+  return `${PATHS.project}/${key}/roadmap/new`;
+}
+
+/** Where one goal is read, or changed. */
+export function goalHref(key: string, id: string, form?: "edit"): string {
+  const base = `${PATHS.project}/${key}/roadmap/${id}`;
+  return form === undefined ? base : `${base}?${form}`;
+}
+
 /**
  * Where a document of a project is read, or a folder of them listed (`""` for the root), and
  * how: a form, a version, or a search over all of them.

package/src/routes.ts

@@ -17,8 +17,17 @@ export const REST_ROUTES = {
   tokens: "/api/v1/tokens",
   /** Connecting an agent (ADR-0011): begun as nobody, approved by a person, claimed by the command. */
   connect: "/api/v1/connect",
+  /** The categories tasks are sorted into (ADR-0019): the workspace's vocabulary, kept by an administrator. */
+  categories: "/api/v1/categories",
+  /** What is on the asker's plate across the projects they may see: their open tasks, and the decisions waiting. */
+  work: "/api/v1/work",
 } as const;
 
+/** The REST path of one category, by its key. */
+export function categoryPath(key: string): string {
+  return `${REST_ROUTES.categories}/${encodeURIComponent(key)}`;
+}
+
 /** Where the command claims the token of a connection, with its secret. */
 export const CLAIM_PATH = `${REST_ROUTES.connect}/claim`;
 
@@ -44,6 +53,7 @@ export const PROJECT_COLLECTIONS = [
   "skills",
   "members",
   "docs",
+  "goals",
 ] as const;
 
 export type ProjectCollection = (typeof PROJECT_COLLECTIONS)[number];
@@ -104,3 +114,12 @@ export function projectPath(key: string, collection?: ProjectCollection, id?: st
     ? `${base}/${collection}`
     : `${base}/${collection}/${encodeURIComponent(id)}`;
 }
+
+/**
+ * Where a project's own image for its mark is read, with the hash as a version where the image
+ * is known, so that a browser's copy is asked for again only when the image changes.
+ */
+export function projectIconPath(key: string, icon?: { readonly sha256: string } | null): string {
+  const base = `${projectPath(key)}/icon`;
+  return icon === undefined || icon === null ? base : `${base}?v=${icon.sha256.slice(0, 16)}`;
+}

package/src/schemas.ts

@@ -7,6 +7,8 @@ import { isDocumentPath } from "./documents.js";
 import {
   MAX_AGENT_LENGTH,
   MAX_BODY_LENGTH,
+  MAX_CATEGORY_KEY_LENGTH,
+  MAX_CATEGORY_NAME_LENGTH,
   MAX_DOCUMENT_LENGTH,
   MAX_DOCUMENT_PATH_LENGTH,
   MAX_FILE_NAME_LENGTH,
@@ -19,6 +21,7 @@ import {
   MAX_PROJECT_DESCRIPTION_LENGTH,
   MAX_PROJECT_KEY_LENGTH,
   MAX_PROJECT_NAME_LENGTH,
+  MAX_PROJECT_SYMBOL_LENGTH,
   MAX_QUESTION_LENGTH,
   MAX_SECRET_LENGTH,
   MAX_SKILLS_ADDRESS_LENGTH,
@@ -32,9 +35,13 @@ import {
 import { hasForbiddenCodePoint } from "./text.js";
 import {
   ARTIFACT_KINDS,
+  CATEGORY_COLORS,
+  COLOR_NAMES,
   EVENT_KINDS,
+  GOAL_STATES,
   LINK_SOURCES,
   PERSON_ROLES,
+  PROJECT_ICON_TYPES,
   PROJECT_ROLES,
   PROJECT_VISIBILITIES,
   PROVIDER_KEYS,
@@ -70,6 +77,8 @@ const url = z.string().check(z.trim(), z.maxLength(MAX_URL_LENGTH), z.url({ prot
 const uuid = z.uuid();
 /** An ISO 8601 instant, as the server writes it. */
 const instant = z.iso.datetime();
+/** A calendar day (`2026-10-20`): a plan is made in days, wherever the people are (ADR-0019). */
+const day = z.iso.date();
 const count = z.int().check(z.nonnegative());
 
 /** A person of the workspace, as the pages show them. Nothing here is a secret. */
@@ -154,7 +163,19 @@ const projectKey = z.string().check(
 /** The address of a project's skills, as the standard spells one; the console checks it as one. */
 const skillsAddress = line(MAX_SKILLS_ADDRESS_LENGTH);
 
+/** A project's mark: a letter or two, or a symbol, with no space in it; shown on the project's colour. */
+const projectSymbol = line(MAX_PROJECT_SYMBOL_LENGTH).check(
+  z.refine((value) => !/\s/.test(value), "must have no space in it"),
+);
+
 /** A project of the workspace, as the asker sees it: with what they are in it. */
+/** A project's own image for its mark: the hash it is kept by, which `projectIconPath` reads it with, and its kind. */
+export const restProjectIconSchema = z.object({
+  sha256: z.string().check(z.regex(/^[0-9a-f]{64}$/)),
+  contentType: z.enum(PROJECT_ICON_TYPES),
+});
+export type RestProjectIcon = z.infer<typeof restProjectIconSchema>;
+
 export const restProjectSchema = z.object({
   id: uuid,
   key: projectKey,
@@ -164,6 +185,12 @@ export const restProjectSchema = z.object({
   visibility: z.enum(PROJECT_VISIBILITIES),
   /** The address of the project's skills at the SkillCDN deployment, canonical, or `null` for the organization's. */
   skillsAddress: z.nullable(z.string()),
+  /** The colour of the project's mark, one of the names, or `null` for one chosen from its key. */
+  color: z.nullable(z.enum(COLOR_NAMES)),
+  /** The project's mark, a letter or two or a symbol, or `null` for the first letter of its name. */
+  symbol: z.nullable(z.string()),
+  /** The project's own image for its mark, shown in place of the symbol, or `null` for none. */
+  icon: z.nullable(restProjectIconSchema),
   /** What the asker is in it: an owner configures the project, a member works on it. */
   role: z.enum(PROJECT_ROLES),
   /** How many decisions in it wait for a person. */
@@ -188,6 +215,9 @@ export const restProjectInputSchema = z.object({
   visibility: z.optional(z.enum(PROJECT_VISIBILITIES)),
   /** Left out or `null`: the organization's skills. */
   skillsAddress: z.optional(z.nullable(skillsAddress)),
+  /** Left out or `null`: a colour chosen from the key, and the first letter of the name. */
+  color: z.optional(z.nullable(z.enum(COLOR_NAMES))),
+  symbol: z.optional(z.nullable(projectSymbol)),
 });
 export type RestProjectInput = z.infer<typeof restProjectInputSchema>;
 
@@ -197,6 +227,8 @@ export const restProjectPatchSchema = z.object({
   description: z.optional(paragraphs(MAX_PROJECT_DESCRIPTION_LENGTH)),
   visibility: z.optional(z.enum(PROJECT_VISIBILITIES)),
   skillsAddress: z.optional(z.nullable(skillsAddress)),
+  color: z.optional(z.nullable(z.enum(COLOR_NAMES))),
+  symbol: z.optional(z.nullable(projectSymbol)),
 });
 export type RestProjectPatch = z.infer<typeof restProjectPatchSchema>;
 
@@ -230,6 +262,48 @@ export const restTaskLinkSchema = z.object({
 });
 export type RestTaskLink = z.infer<typeof restTaskLinkSchema>;
 
+/**
+ * A category's key: what the command and the filters say, as a project's key is. Lowercase
+ * letters, digits and hyphens; immutable once the category is made.
+ */
+const categoryKey = z
+  .string()
+  .check(
+    z.maxLength(MAX_CATEGORY_KEY_LENGTH),
+    z.regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, "must be lowercase letters, digits and hyphens"),
+  );
+
+/** A category tasks are sorted into (ADR-0019): the workspace's own word for a kind of work. */
+export const restCategorySchema = z.object({
+  key: categoryKey,
+  name: z.string(),
+  /** One of the names the pages paint a category in. */
+  color: z.enum(CATEGORY_COLORS),
+  createdAt: instant,
+  updatedAt: instant,
+});
+export type RestCategory = z.infer<typeof restCategorySchema>;
+
+/** `GET /api/v1/categories`: the workspace's categories, by name. */
+export const restCategoriesSchema = z.object({ items: z.array(restCategorySchema) });
+export type RestCategories = z.infer<typeof restCategoriesSchema>;
+
+/** What `POST /api/v1/categories` is sent, by an administrator: the key, the name, and a colour or the plain one. */
+export const restCategoryInputSchema = z.object({
+  key: categoryKey,
+  name: line(MAX_CATEGORY_NAME_LENGTH),
+  /** Left out: `gray`. */
+  color: z.optional(z.enum(CATEGORY_COLORS)),
+});
+export type RestCategoryInput = z.infer<typeof restCategoryInputSchema>;
+
+/** What `PATCH /api/v1/categories/<key>` is sent: only what changes; the key does not. */
+export const restCategoryPatchSchema = z.object({
+  name: z.optional(line(MAX_CATEGORY_NAME_LENGTH)),
+  color: z.optional(z.enum(CATEGORY_COLORS)),
+});
+export type RestCategoryPatch = z.infer<typeof restCategoryPatchSchema>;
+
 export const restTaskSchema = z.object({
   id: uuid,
   /** The task's number in its project, the one people say out loud. */
@@ -243,6 +317,18 @@ export const restTaskSchema = z.object({
   assignee: z.nullable(restPersonSchema),
   /** The task this one is part of, or `null`. */
   parentId: z.nullable(uuid),
+  /** The category the task is sorted into, as the workspace keeps it, or `null`. */
+  category: z.nullable(
+    z.object({ key: z.string(), name: z.string(), color: z.enum(CATEGORY_COLORS) }),
+  ),
+  /** The goal of the project's roadmap the task works towards, or `null`. */
+  goalId: z.nullable(uuid),
+  /** The plan (ADR-0019): the day the work is meant to begin, and the day it is due, each or `null`. */
+  startsOn: z.nullable(day),
+  dueOn: z.nullable(day),
+  /** What happened: when the task was first moved past ready, and when it was moved to done; each or `null`. The board keeps both. */
+  startedAt: z.nullable(instant),
+  doneAt: z.nullable(instant),
   links: z.array(restTaskLinkSchema),
   /** How many decisions about this task wait for a person. */
   openDecisions: count,
@@ -253,8 +339,8 @@ export const restTaskSchema = z.object({
 });
 export type RestTask = z.infer<typeof restTaskSchema>;
 
-/** `GET /api/v1/projects/<key>/tasks`: the board, newest first. */
-export const restTasksSchema = z.object({ items: z.array(restTaskSchema) });
+/** `GET /api/v1/projects/<key>/tasks`: a page of the board, newest first, and whether there is more after it. */
+export const restTasksSchema = z.object({ items: z.array(restTaskSchema), more: z.boolean() });
 export type RestTasks = z.infer<typeof restTasksSchema>;
 
 const taskLinkInput = z.object({
@@ -270,6 +356,13 @@ export const restTaskInputSchema = z.object({
   priority: z.optional(z.enum(TASK_PRIORITIES)),
   assigneeId: z.optional(z.nullable(uuid)),
   parentId: z.optional(z.nullable(uuid)),
+  /** The key of a category of the workspace, or `null` for none. */
+  category: z.optional(z.nullable(categoryKey)),
+  /** A goal of the project, or `null` for none. */
+  goalId: z.optional(z.nullable(uuid)),
+  /** The plan, in days; the due day is not before the start. */
+  startsOn: z.optional(z.nullable(day)),
+  dueOn: z.optional(z.nullable(day)),
   links: z.optional(z.array(taskLinkInput).check(z.maxLength(MAX_LINKS))),
 });
 export type RestTaskInput = z.infer<typeof restTaskInputSchema>;
@@ -282,10 +375,68 @@ export const restTaskPatchSchema = z.object({
   priority: z.optional(z.enum(TASK_PRIORITIES)),
   assigneeId: z.optional(z.nullable(uuid)),
   parentId: z.optional(z.nullable(uuid)),
+  category: z.optional(z.nullable(categoryKey)),
+  goalId: z.optional(z.nullable(uuid)),
+  startsOn: z.optional(z.nullable(day)),
+  dueOn: z.optional(z.nullable(day)),
   links: z.optional(z.array(taskLinkInput).check(z.maxLength(MAX_LINKS))),
 });
 export type RestTaskPatch = z.infer<typeof restTaskPatchSchema>;
 
+/** How many tasks a goal has in each state: what its progress is read from, live. */
+export const restTaskCountsSchema = z.object({
+  idea: count,
+  ready: count,
+  in_progress: count,
+  in_review: count,
+  done: count,
+  dropped: count,
+});
+export type RestTaskCounts = z.infer<typeof restTaskCountsSchema>;
+
+/**
+ * A goal of a project's roadmap (ADR-0019): what the project works towards, with the day it is
+ * meant to be reached by, and how far the tasks under it are.
+ */
+export const restGoalSchema = z.object({
+  id: uuid,
+  title: z.string(),
+  /** Markdown: what reaching the goal means. Shown as text or rendered to elements, never as HTML. */
+  body: z.string(),
+  state: z.enum(GOAL_STATES),
+  /** The day the goal is meant to be reached by, or `null`. */
+  dueOn: z.nullable(day),
+  createdBy: restPersonSchema,
+  /** The tasks that work towards it, counted by state. */
+  taskCounts: restTaskCountsSchema,
+  createdAt: instant,
+  updatedAt: instant,
+});
+export type RestGoal = z.infer<typeof restGoalSchema>;
+
+/** `GET /api/v1/projects/<key>/goals`: the roadmap, the active goals first. */
+export const restGoalsSchema = z.object({ items: z.array(restGoalSchema) });
+export type RestGoals = z.infer<typeof restGoalsSchema>;
+
+/** What `POST /api/v1/projects/<key>/goals` is sent: the title, and the rest with defaults. */
+export const restGoalInputSchema = z.object({
+  title: line(MAX_TITLE_LENGTH),
+  body: z.optional(body),
+  /** Left out: `planned`. */
+  state: z.optional(z.enum(GOAL_STATES)),
+  dueOn: z.optional(z.nullable(day)),
+});
+export type RestGoalInput = z.infer<typeof restGoalInputSchema>;
+
+/** What `PATCH /api/v1/projects/<key>/goals/<id>` is sent: only what changes. */
+export const restGoalPatchSchema = z.object({
+  title: z.optional(line(MAX_TITLE_LENGTH)),
+  body: z.optional(body),
+  state: z.optional(z.enum(GOAL_STATES)),
+  dueOn: z.optional(z.nullable(day)),
+});
+export type RestGoalPatch = z.infer<typeof restGoalPatchSchema>;
+
 export const restDecisionOptionSchema = z.object({
   /** What an answer names: stable for the life of the decision. */
   id: z.string(),
@@ -324,10 +475,32 @@ export const restDecisionSchema = z.object({
 });
 export type RestDecision = z.infer<typeof restDecisionSchema>;
 
-/** `GET /api/v1/projects/<key>/decisions`: the ones that wait first, newest first within each. */
-export const restDecisionsSchema = z.object({ items: z.array(restDecisionSchema) });
+/** `GET /api/v1/projects/<key>/decisions`: a page, the ones that wait first, newest first within each, and whether there is more. */
+export const restDecisionsSchema = z.object({
+  items: z.array(restDecisionSchema),
+  more: z.boolean(),
+});
 export type RestDecisions = z.infer<typeof restDecisionsSchema>;
 
+/** The project a thing on a person's plate belongs to, named and marked for the page to say, link and show it. */
+const projectRef = z.object({
+  key: projectKey,
+  name: z.string(),
+  color: z.nullable(z.enum(COLOR_NAMES)),
+  symbol: z.nullable(z.string()),
+  icon: z.nullable(restProjectIconSchema),
+});
+
+/**
+ * `GET /api/v1/work`: what is on the asker's plate across the projects they may see (ADR-0019):
+ * the open tasks assigned to them, and the decisions that wait for a person, each with its project.
+ */
+export const restWorkSchema = z.object({
+  tasks: z.array(z.object({ project: projectRef, task: restTaskSchema })),
+  decisions: z.array(z.object({ project: projectRef, decision: restDecisionSchema })),
+});
+export type RestWork = z.infer<typeof restWorkSchema>;
+
 /** What `POST /api/v1/projects/<key>/decisions` is sent: the question, its context, and the options. */
 export const restDecisionInputSchema = z.object({
   question: line(MAX_QUESTION_LENGTH),
@@ -363,7 +536,7 @@ export type RestAnswerInput = z.infer<typeof restAnswerInputSchema>;
 export const restEventDataSchema = z.object({
   number: z.optional(z.int()),
   title: z.optional(z.string()),
-  /** For `task.updated`, `project.updated` and `decision.updated`: which fields changed. */
+  /** For `task.updated`, `project.updated`, `goal.updated` and `decision.updated`: which fields changed. */
   fields: z.optional(z.array(z.string())),
   /** For the events about a document: its path, and the version written. */
   path: z.optional(z.string()),
@@ -406,6 +579,8 @@ export const restEventSchema = z.object({
   runId: z.nullable(uuid),
   /** The document it is about, or `null`. */
   documentId: z.nullable(uuid),
+  /** The goal it is about, or `null`. */
+  goalId: z.nullable(uuid),
   data: restEventDataSchema,
   createdAt: instant,
 });
@@ -458,6 +633,11 @@ export const restRunSchema = z.object({
   status: z.enum(RUN_STATUSES),
   startedAt: instant,
   endedAt: z.nullable(instant),
+  /**
+   * When the agent was last heard from on this run: when it began, reported, handed in or
+   * asked. The board cannot know whether an agent still runs; this is what it knows.
+   */
+  lastHeardAt: instant,
   /** What the agent said when the run ended, in Markdown, or `null`. */
   summary: z.nullable(z.string()),
   /** Oldest first. */
@@ -468,8 +648,8 @@ export const restRunSchema = z.object({
 });
 export type RestRun = z.infer<typeof restRunSchema>;
 
-/** `GET /api/v1/projects/<key>/runs`: the runs, newest first. */
-export const restRunsSchema = z.object({ items: z.array(restRunSchema) });
+/** `GET /api/v1/projects/<key>/runs`: a page of the runs, newest first, and whether there is more. */
+export const restRunsSchema = z.object({ items: z.array(restRunSchema), more: z.boolean() });
 export type RestRuns = z.infer<typeof restRunsSchema>;
 
 /** `GET .../events?after=`: what happened after that number, oldest first. */