@yannelli/paseo-linear-plugin 1.1.0-beta.2 → 1.1.0-beta.4

package/server/live.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { z } from "zod";
 import { relativePath } from "../shared/activity";
+import { knowledgeLines, liveProjectRpc, type ProjectKnowledge, resolvePaths, toAreaRef } from "../shared/knowledge";
 import { type IssueDetail, ISSUE_CARD_KIND } from "../shared/linear";
 import {
   ExploreResultSchema,
@@ -29,6 +30,7 @@ import {
   startInternalRun,
 } from "./agent-runs";
 import type { LinearAccess } from "./handlers";
+import { type KnowledgeService, knowledgeFor } from "./knowledge";
 import { fileLinks } from "./links";
 import { subagentLogs } from "./subagent-logs";
 import type { LaunchQueue, MapStore } from "./stores";
@@ -97,8 +99,9 @@ export async function listDirectories(cwd: string, dirs: readonly string[]) {
   return results;
 }
 
-export function explorePrompt(issue: IssueDetail): string {
+export function explorePrompt(issue: IssueDetail, knowledge: ProjectKnowledge | null = null): string {
   const keys = [issue.identifier, ...issue.children.map((child) => child.identifier)];
+  const map = knowledgeLines(knowledge);
   return [
     `Map this repository for Linear issue ${issue.identifier}: ${issue.title}`,
     "",
@@ -106,6 +109,7 @@ export function explorePrompt(issue: IssueDetail): string {
     "",
     issueSnapshot(issue, { includeComments: false }),
     "",
+    ...(map.length > 0 ? [...map, ""] : []),
     "List the files an engineer will most likely read or change for this issue and each sub-issue.",
     `Include files that will probably be created, at their expected path. List at most ${MAX_EXPLORE_FILES} files.`,
     `Set "issue" to the sub-issue key the file belongs to, or ${issue.identifier} for the whole issue.`,
@@ -138,6 +142,7 @@ export interface LiveDependencies {
   access: LinearAccess;
   maps: MapStore;
   launches: LaunchQueue;
+  knowledge: KnowledgeService;
   readSettings(): Promise<LinearSettings | null>;
 }
 
@@ -159,7 +164,7 @@ export async function startLaunch(workspace: WorkspaceHandle, launch: LaunchInpu
 }
 
 export function registerLive(server: PluginServerContext, dependencies: LiveDependencies) {
-  const { access, maps, launches, readSettings } = dependencies;
+  const { access, maps, launches, knowledge, readSettings } = dependencies;
   const jobs = createJobStore<IssueMap>();
   const recovering = new Map<string, Promise<Job | null>>();
   const recoveredAt = new Map<string, number>();
@@ -230,6 +235,14 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     return { links: await fileLinks(agent.cwd, files) };
   });
 
+  server.handle(liveProjectRpc, async ({ agentId, paths }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const known = await knowledgeFor(paseo, knowledge, agent.projectId);
+    if (!known) return { areas: [], resolved: [] };
+    const resolved = [...resolvePaths(paths, known.files)].map(([from, to]) => ({ from, to }));
+    return { areas: known.areas.map(toAreaRef), resolved };
+  });
+
   server.handle(clearMapRpc, async ({ agentId }, { paseo }) => {
     const agent = await agentInfo(paseo, agentId);
     const identifier = agent.labels[AGENT_LABELS.issue];
@@ -267,6 +280,8 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
   interface ExploreTarget {
     identifier: string;
     keyScope: string | null;
+    /** Paseo project whose saved knowledge goes into the prompt. */
+    projectId: string | null;
     cwd: string;
     /** Opened only when a new run starts. */
     workspace: () => Promise<WorkspaceHandle>;
@@ -293,6 +308,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
       const issue = await linear.getIssue(identifier);
       const labels: Record<string, string> = { [AGENT_LABELS.explore]: identifier };
       if (target.keyScope) labels[AGENT_LABELS.project] = target.keyScope;
+      const known = await knowledgeFor(paseo, knowledge, target.projectId);
       const run = await startInternalRun({
         paseo,
         workspace: await target.workspace(),
@@ -300,7 +316,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
         provider: target.provider,
         effort: target.effort,
         title: `Explore ${identifier}`,
-        prompt: explorePrompt(issue),
+        prompt: explorePrompt(issue, known),
         labels,
         schema: ExploreResultSchema,
         timeoutMs: EXPLORE_TIMEOUT_MS,
@@ -326,6 +342,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     const job = await ensureExplore(paseo, {
       identifier,
       keyScope: agent.labels[AGENT_LABELS.project] ?? null,
+      projectId: agent.projectId,
       cwd,
       workspace: async () =>
         workspaceId ? paseo.workspaces.ref(workspaceId) : paseo.workspaces.open(cwd),
@@ -344,6 +361,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     const job = await ensureExplore(paseo, {
       identifier: input.identifier,
       keyScope: input.keyScope,
+      projectId: info.projectId,
       cwd: info.workspaceDirectory ?? info.projectRootPath,
       workspace: async () => workspace,
       provider: settings?.live.exploreProvider || input.agent.config.provider,

package/server/stores.ts

@@ -7,7 +7,7 @@ const MAX_MAPS = 200;
 /** A launch still waiting after this long is dropped, so a stale one never starts by surprise. */
 export const PENDING_LAUNCH_MAX_AGE_MS = 60 * 60_000;
 
-interface JsonFile<T> {
+export interface JsonFile<T> {
   read(): Promise<T>;
   /** Changes run one at a time, so a read, change, and write never interleave. */
   update<R>(change: (current: T) => { next: T; result: R }): Promise<R>;

package/shared/custom-icon.ts

@@ -12,6 +12,44 @@ export const LINEAR_INDIGO = "#5E6AD2";
 export const MAX_SVG_LENGTH = 64_000;
 export const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
+/** Paseo draws panel tabs, the new tab menu, and Command Center with Lucide names only. */
+export const BUILT_IN_ICON = "SquareKanban";
+export const MENU_ICONS: readonly { name: string; label: string }[] = [
+  { name: BUILT_IN_ICON, label: "Board (default)" },
+  ...[
+    ["Kanban", "Kanban"],
+    ["LayoutGrid", "Grid"],
+    ["ListTodo", "To-do list"],
+    ["ClipboardList", "Clipboard"],
+    ["CircleDot", "Circle dot"],
+    ["Target", "Target"],
+    ["Zap", "Lightning"],
+    ["Rocket", "Rocket"],
+    ["Star", "Star"],
+    ["Hexagon", "Hexagon"],
+    ["Triangle", "Triangle"],
+    ["Diamond", "Diamond"],
+    ["Box", "Box"],
+    ["Layers", "Layers"],
+    ["Compass", "Compass"],
+    ["Flag", "Flag"],
+    ["Bookmark", "Bookmark"],
+    ["Ticket", "Ticket"],
+    ["Bug", "Bug"],
+    ["Sparkles", "Sparkles"],
+    ["Bot", "Bot"],
+    ["Gem", "Gem"],
+    ["Flame", "Flame"],
+    ["Shapes", "Shapes"],
+    ["Orbit", "Orbit"],
+    ["Workflow", "Workflow"],
+    ["Puzzle", "Puzzle"],
+    ["Atom", "Atom"],
+    ["Command", "Command"],
+  ].map(([name = "", label = ""]) => ({ name, label })),
+];
+const LUCIDE_NAME = /^[A-Z][A-Za-z0-9]*$/;
+
 export const IconSettingsSchema = z.object({
   /** Checked SVG markup. Empty uses the built-in icon. */
   svg: z.string().max(MAX_SVG_LENGTH).default(""),
@@ -20,6 +58,8 @@ export const IconSettingsSchema = z.object({
   color: z.string().regex(HEX_COLOR).default(LINEAR_INDIGO),
   /** Fill shapes that only have an outline. */
   solid: z.boolean().default(false),
+  /** The Lucide icon for panel tabs, the new tab menu, and Command Center. */
+  menu: z.string().regex(LUCIDE_NAME).default(BUILT_IN_ICON),
 });
 export type IconSettings = z.infer<typeof IconSettingsSchema>;
 

package/shared/graph-camera.ts

@@ -17,6 +17,11 @@ export interface Box {
   bottom: number;
 }
 
+/** A box with the point the view centers on when the box still fits around it. */
+export interface Focus extends Box {
+  center: Point;
+}
+
 export const FIT: Camera = { x: 0, y: 0, zoom: 1 };
 export const MIN_ZOOM = 1;
 export const MAX_ZOOM = 4;
@@ -27,6 +32,11 @@ const PAD_Y = 56;
 
 const clamp = (value: number, low: number, high: number) => Math.min(high, Math.max(low, value));
 
+/** How much nodes, labels, and cursors grow on screen: less than the zoom, so they stay readable. */
+export function growth(zoom: number): number {
+  return Math.sqrt(zoom);
+}
+
 /** Where a canvas point draws in the view. */
 export function project(camera: Camera, at: Point, width: number, height: number): Point {
   return {
@@ -61,21 +71,31 @@ export function zoomAt(camera: Camera, at: Point, factor: number, width: number,
   return clampCamera({ zoom, x: at.x - cx - zoom * (px - cx), y: at.y - cy - zoom * (py - cy) }, width, height);
 }
 
-/** Shows the box as large as fits in the view, up to the auto zoom. */
-export function frameBox(box: Box, width: number, height: number): Camera {
+/** The center nearest `wanted` that keeps the span from low to high in a view of this size. */
+function centerFor(wanted: number, low: number, high: number, half: number): number {
+  return high - low >= half * 2 ? (low + high) / 2 : clamp(wanted, high - half, low + half);
+}
+
+/** Shows the box as large as fits in the view, up to the auto zoom, centered on its focus. */
+export function frameBox(box: Box | Focus, width: number, height: number): Camera {
   const fit = Math.min(width / Math.max(1, box.right - box.left), height / Math.max(1, box.bottom - box.top));
   const zoom = clamp(fit, MIN_ZOOM, AUTO_ZOOM);
-  const x = zoom * (width / 2 - (box.left + box.right) / 2);
-  const y = zoom * (height / 2 - (box.top + box.bottom) / 2);
-  return clampCamera({ zoom, x, y }, width, height);
+  const wanted = "center" in box ? box.center : { x: (box.left + box.right) / 2, y: (box.top + box.bottom) / 2 };
+  const middleX = centerFor(wanted.x, box.left, box.right, width / 2 / zoom);
+  const middleY = centerFor(wanted.y, box.top, box.bottom, height / 2 / zoom);
+  return clampCamera({ zoom, x: zoom * (width / 2 - middleX), y: zoom * (height / 2 - middleY) }, width, height);
 }
 
 // The area auto mode shows: the nodes the running agents work on and their neighbors, with
 // room for labels and cursors. Null when no agent works on a node other than the issue.
-export function focusBox(graph: Graph, positions: ReadonlyMap<string, Point>, targets: Iterable<string>): Box | null {
+export function focusBox(graph: Graph, positions: ReadonlyMap<string, Point>, targets: Iterable<string>): Focus | null {
   const ids = new Set<string>();
   for (const target of targets) if (target !== graph.root) ids.add(target);
   if (ids.size === 0) return null;
+  const spots = [...ids].flatMap((id) => positions.get(id) ?? []);
+  const center = spots.length
+    ? { x: spots.reduce((sum, at) => sum + at.x, 0) / spots.length, y: spots.reduce((sum, at) => sum + at.y, 0) / spots.length }
+    : null;
   for (const edge of graph.edges) {
     if (ids.has(edge.from) && edge.to !== graph.root) ids.add(edge.to);
     else if (ids.has(edge.to) && edge.from !== graph.root) ids.add(edge.from);
@@ -88,6 +108,6 @@ export function focusBox(graph: Graph, positions: ReadonlyMap<string, Point>, ta
       ? { left: Math.min(box.left, at.x), top: Math.min(box.top, at.y), right: Math.max(box.right, at.x), bottom: Math.max(box.bottom, at.y) }
       : { left: at.x, top: at.y, right: at.x, bottom: at.y };
   }
-  if (!box) return null;
-  return { left: box.left - PAD_X, top: box.top - PAD_Y, right: box.right + PAD_X, bottom: box.bottom + PAD_Y };
+  if (!box || !center) return null;
+  return { left: box.left - PAD_X, top: box.top - PAD_Y, right: box.right + PAD_X, bottom: box.bottom + PAD_Y, center };
 }

package/shared/graph-geometry.ts

@@ -6,31 +6,36 @@ export interface Point {
   y: number;
 }
 
-export interface Route {
-  points: Point[];
+export interface Route<P extends Point = Point> {
+  points: P[];
   /** Each point's share of the whole distance, from 0 to 1. */
   stops: number[];
   length: number;
 }
 
-/** Where a route is at a share of its distance, from 0 to 1. */
-export function pointAt(path: Route, share: number): Point {
+/** Where a route is at a share of its distance, from 0 to 1. Mixes every number of the points. */
+export function pointAt<P extends Point>(path: Route<P>, share: number): P {
   const at = Math.min(1, Math.max(0, share));
   for (let index = 1; index < path.stops.length; index += 1) {
     const stop = path.stops[index] as number;
     if (at > stop) continue;
     const before = path.stops[index - 1] as number;
-    const from = path.points[index - 1] as Point;
-    const to = path.points[index] as Point;
+    const from = path.points[index - 1] as P;
+    const to = path.points[index] as P;
     const part = stop > before ? (at - before) / (stop - before) : 1;
-    return { x: from.x + (to.x - from.x) * part, y: from.y + (to.y - from.y) * part };
+    const mixed: Record<string, unknown> = { ...(to as object) };
+    for (const [key, value] of Object.entries(to as object)) {
+      const start = (from as Record<string, unknown>)[key];
+      if (typeof value === "number" && typeof start === "number") mixed[key] = start + (value - start) * part;
+    }
+    return mixed as P;
   }
-  return path.points[path.points.length - 1] as Point;
+  return path.points[path.points.length - 1] as P;
 }
 
 /** A route through the points without zero-length steps, or null when there is nowhere to go. */
-export function route(points: readonly Point[]): Route | null {
-  const kept: Point[] = [];
+export function route<P extends Point>(points: readonly P[]): Route<P> | null {
+  const kept: P[] = [];
   const steps = [0];
   for (const point of points) {
     const last = kept[kept.length - 1];
@@ -84,21 +89,27 @@ export interface PlacedLabel {
   short: boolean;
 }
 
-// Places labels in request order at the first spot that overlaps no node or placed label,
-// moved inside the box when it would cross an edge. A label with no free spot is hidden.
+export interface Rect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+// Places labels in request order at the first spot that overlaps no node, other obstacle, or
+// placed label, moved inside the box when it would cross an edge. Others are hidden.
 export function placeLabels(
   requests: readonly LabelRequest[],
   width: number,
   height: number,
-  nodes: readonly { at: Point; radius: number }[] = [],
+  obstacles: readonly ({ at: Point; radius: number } | Rect)[] = [],
   gap = 3,
 ): Map<string, PlacedLabel> {
-  const placed = nodes.map(({ at, radius }) => ({
-    left: at.x - radius,
-    right: at.x + radius,
-    top: at.y - radius,
-    bottom: at.y + radius,
-  }));
+  const placed: Rect[] = obstacles.map((shape) =>
+    "at" in shape
+      ? { left: shape.at.x - shape.radius, right: shape.at.x + shape.radius, top: shape.at.y - shape.radius, bottom: shape.at.y + shape.radius }
+      : { ...shape },
+  );
   const shown = new Map<string, PlacedLabel>();
   for (const request of requests) {
     const tries = [{ ...request, short: false }];

package/shared/knowledge.ts

@@ -0,0 +1,255 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+// Project knowledge: what the daemon learns about a project's files without an agent. It is
+// kept on disk, so explore and setup prompts, ticket-text maps, and Linear Live can use it.
+
+export const AREA_KINDS = ["service", "package", "folder"] as const;
+export type AreaKind = (typeof AREA_KINDS)[number];
+
+export const AreaSchema = z.object({
+  /** Folder with a trailing slash; "" is the repository root. */
+  path: z.string(),
+  name: z.string(),
+  kind: z.enum(AREA_KINDS),
+  /** What the folder holds, from its name, such as "backend" or "tests"; "" when unknown. */
+  role: z.string(),
+  /** Files that define it, such as package.json or Dockerfile. */
+  manifests: z.array(z.string()),
+  /** Files under the folder, at any depth. */
+  files: z.number(),
+  languages: z.array(z.string()),
+  /** One line from the setup agent; "" until it writes one. */
+  summary: z.string(),
+});
+export type Area = z.infer<typeof AreaSchema>;
+
+/** The part of an area the app needs to label files. */
+export const AreaRefSchema = AreaSchema.pick({
+  path: true,
+  name: true,
+  kind: true,
+  role: true,
+  summary: true,
+});
+export type AreaRef = z.infer<typeof AreaRefSchema>;
+
+const CountSchema = z.object({ name: z.string(), files: z.number() });
+
+export const ProjectKnowledgeSchema = z.object({
+  projectId: z.string(),
+  rootPath: z.string(),
+  inspectedAt: z.string(),
+  source: z.enum(["git", "walk"]),
+  /** Repo-relative file paths, sorted, at most MAX_KNOWLEDGE_FILES. */
+  files: z.array(z.string()),
+  fileCount: z.number(),
+  truncated: z.boolean(),
+  areas: z.array(AreaSchema),
+  languages: z.array(CountSchema),
+  /** Files that guide agents and contributors, such as AGENTS.md and CI workflows. */
+  guides: z.array(z.string()),
+  /** Commands the repository defines, such as "npm run check". */
+  commands: z.array(z.string()),
+  /** One line from the setup agent about the project; "" until it writes one. */
+  summary: z.string(),
+  summarizedAt: z.string().nullable(),
+});
+export type ProjectKnowledge = z.infer<typeof ProjectKnowledgeSchema>;
+
+/** What the app gets: everything but the file list, plus file counts per top folder. */
+export const ProjectBriefSchema = ProjectKnowledgeSchema.omit({ files: true }).extend({
+  folders: z.array(CountSchema),
+});
+export type ProjectBrief = z.infer<typeof ProjectBriefSchema>;
+
+export const MAX_KNOWLEDGE_FILES = 20_000;
+export const MAX_RESOLVE_PATHS = 200;
+
+/** Saved knowledge of a project; the daemon inspects the project first when it has none. */
+export const knowledgeGetRpc = defineRpc({
+  name: "linear.knowledge.get",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+export const knowledgeInspectRpc = defineRpc({
+  name: "linear.knowledge.inspect",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+/** The areas of an agent's project, and ticket paths matched to the project's real files. */
+export const liveProjectRpc = defineRpc({
+  name: "linear.live.project",
+  input: z.object({
+    agentId: z.string().min(1),
+    paths: z.array(z.string()).max(MAX_RESOLVE_PATHS),
+  }),
+  output: z.object({
+    areas: z.array(AreaRefSchema),
+    resolved: z.array(z.object({ from: z.string(), to: z.string() })),
+  }),
+});
+
+export function toAreaRef(area: Area): AreaRef {
+  return { path: area.path, name: area.name, kind: area.kind, role: area.role, summary: area.summary };
+}
+
+/** The deepest area whose folder holds the path. */
+export function areaOf<A extends { path: string }>(path: string, areas: readonly A[]): A | null {
+  let best: A | null = null;
+  for (const area of areas) {
+    if (path.startsWith(area.path) && (!best || area.path.length > best.path.length)) best = area;
+  }
+  return best;
+}
+
+/** Such as "billing-api · service", "server · backend", or "docs". */
+export function areaLabel(area: AreaRef): string {
+  const what = area.role || (area.kind === "folder" ? "" : area.kind);
+  return what && what.toLowerCase() !== area.name.toLowerCase() ? `${area.name} · ${what}` : area.name;
+}
+
+function topFolder(path: string): string {
+  const index = path.indexOf("/");
+  return index < 0 ? "./" : path.slice(0, index + 1);
+}
+
+/** File counts per top folder; "./" counts files at the root. */
+export function topFolders(files: readonly string[]): { name: string; files: number }[] {
+  const counts = new Map<string, number>();
+  for (const file of files) counts.set(topFolder(file), (counts.get(topFolder(file)) ?? 0) + 1);
+  return [...counts]
+    .map(([name, count]) => ({ name, files: count }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Where an off-map file is: its area, or its top folder when the project has no knowledge. */
+export function whereLabel(path: string, areas: readonly AreaRef[]): string {
+  const area = areaOf(path, areas);
+  return area && area.path !== "" ? areaLabel(area) : topFolder(path);
+}
+
+/** Folders to the given depth with their file counts, indented, for prompts. */
+export function folderLines(files: readonly string[], depth = 2, limit = 60): string[] {
+  const counts = new Map<string, number>();
+  for (const file of files) {
+    const parts = file.split("/").slice(0, -1);
+    for (let level = 1; level <= Math.min(depth, parts.length); level += 1) {
+      const dir = `${parts.slice(0, level).join("/")}/`;
+      counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    }
+  }
+  const dirs = [...counts.keys()].sort();
+  if (dirs.length > limit && depth > 1) return folderLines(files, depth - 1, limit);
+  const lines = dirs.slice(0, limit).map((dir) => {
+    const indent = "  ".repeat(dir.split("/").length - 2);
+    return `${indent}${dir} (${counts.get(dir)})`;
+  });
+  if (dirs.length > limit) lines.push(`... ${dirs.length - limit} more folders`);
+  return lines;
+}
+
+function countLine(entries: readonly { name: string; files: number }[]): string {
+  return entries.map((entry) => `${entry.name} ${entry.files}`).join(", ");
+}
+
+/** The project map an agent prompt starts from. Empty without knowledge. */
+export function knowledgeLines(knowledge: ProjectKnowledge | null): string[] {
+  if (!knowledge) return [];
+  const source = knowledge.source === "git" ? "git ls-files" : "a folder walk";
+  const lines = [
+    `Project map from the plugin's inspection (${knowledge.inspectedAt}, by ${source}). Start from`,
+    "it instead of listing the whole repository; files may have changed since.",
+  ];
+  if (knowledge.summary) lines.push(`- Project: ${knowledge.summary}`);
+  const truncated = knowledge.truncated ? ", list truncated" : "";
+  lines.push(`- ${knowledge.fileCount} files${truncated}. Languages: ${countLine(knowledge.languages) || "unknown"}.`);
+  if (knowledge.guides.length > 0) lines.push(`- Guides: ${knowledge.guides.join(", ")}`);
+  if (knowledge.commands.length > 0) lines.push(`- Commands: ${knowledge.commands.join(", ")}`);
+  if (knowledge.areas.length > 0) {
+    lines.push("Areas (services, packages, and main folders):");
+    for (const area of knowledge.areas) {
+      const manifests = area.manifests.length > 0 ? ` [${area.manifests.join(", ")}]` : "";
+      const languages = area.languages.length > 0 ? `, ${area.languages.join("/")}` : "";
+      const summary = area.summary ? `: ${area.summary}` : "";
+      const files = `${area.files} ${area.files === 1 ? "file" : "files"}`;
+      lines.push(`- ${area.path || "./"} ${areaLabel(area)}${manifests}, ${files}${languages}${summary}`);
+    }
+  }
+  lines.push("Folders (file count):", ...folderLines(knowledge.files));
+  return lines;
+}
+
+function byName(files: readonly string[]): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const file of files) {
+    const name = file.slice(file.lastIndexOf("/") + 1);
+    const known = index.get(name);
+    if (known) known.push(file);
+    else index.set(name, [file]);
+  }
+  return index;
+}
+
+function dirsOf(files: readonly string[]): Set<string> {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    let index = file.indexOf("/");
+    while (index >= 0) {
+      dirs.add(file.slice(0, index + 1));
+      index = file.indexOf("/", index + 1);
+    }
+  }
+  return dirs;
+}
+
+/** Ticket paths matched to real files: "linear.ts" to "server/linear.ts" when only one fits. */
+export function resolvePaths(paths: readonly string[], files: readonly string[]): Map<string, string> {
+  const known = new Set(files);
+  const names = byName(files);
+  let dirs: Set<string> | null = null;
+  const resolved = new Map<string, string>();
+  for (const path of paths) {
+    let matches: string[];
+    if (path.endsWith("/")) {
+      dirs ??= dirsOf(files);
+      if (dirs.has(path)) continue;
+      matches = [...dirs].filter((dir) => dir.endsWith(`/${path}`));
+    } else {
+      if (known.has(path)) continue;
+      const name = path.slice(path.lastIndexOf("/") + 1);
+      matches = (names.get(name) ?? []).filter((file) => file === name || file.endsWith(`/${path}`));
+    }
+    if (matches.length === 1 && matches[0]) resolved.set(path, matches[0]);
+  }
+  return resolved;
+}
+
+const KINDS_SAID = "(?:service|package|app|module|library|lib|worker|folder|directory|dir)";
+
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function aliases(area: AreaRef): string[] {
+  const folder = area.path.replace(/\/$/, "").split("/").pop() ?? "";
+  return [...new Set([area.name, folder])].filter((alias) => alias.length >= 3);
+}
+
+// A service or package counts when its name appears; a plain folder only when the text says
+// "the docs folder" or similar, since folder names like "server" are common words.
+function mentions(text: string, alias: string, plain: boolean): boolean {
+  const word = `(?:^|[^\\w@/.-])${escapeRegex(alias)}(?![\\w@/-])`;
+  if (plain && alias.length >= 4 && new RegExp(word, "i").test(text)) return true;
+  return new RegExp(`${word}\\s+${KINDS_SAID}\\b`, "i").test(text);
+}
+
+/** Areas the text names, other than the whole repository. */
+export function areasIn(text: string, areas: readonly AreaRef[]): AreaRef[] {
+  return areas.filter(
+    (area) =>
+      area.path !== "" && aliases(area).some((alias) => mentions(text, alias, area.kind !== "folder")),
+  );
+}

package/shared/live.ts

@@ -1,6 +1,7 @@
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
 import { McpHttpServerSchema, ToolPolicySchema } from "./agent-tools";
+import { type AreaRef, areasIn } from "./knowledge";
 import { IssueCardSchema, WorkflowStateSchema } from "./linear";
 
 // Contracts for Linear Live, todo sync, and project setup. Agents the plugin starts for itself
@@ -40,6 +41,9 @@ export const InitProposalSchema = z.object({
   steps: z.array(z.string()).default([]),
   implement: z.string().default(""),
   review: z.string().default(""),
+  /** Saved to the project knowledge at once; not part of the prompt proposal. */
+  summary: z.string().default(""),
+  areas: z.array(z.object({ path: z.string(), summary: z.string() })).max(80).default([]),
 });
 export type InitProposal = z.infer<typeof InitProposalSchema>;
 
@@ -194,18 +198,30 @@ export interface SemanticIssue {
   children: readonly { identifier: string; title: string }[];
 }
 
+/** What project knowledge adds to a ticket-text map. */
+export interface MapHints {
+  /** Ticket paths matched to real files, such as "linear.ts" to "server/linear.ts". */
+  resolved?: ReadonlyMap<string, string>;
+  /** A service or package the text names puts its folder on the map. */
+  areas?: readonly AreaRef[];
+}
+
 // Linear sends sub-issue titles but not their descriptions, so a path in the parent's text
 // belongs to the sub-issue its line names and otherwise to the parent.
-export function semanticMap(issue: SemanticIssue, now = new Date()): IssueMap {
+export function semanticMap(issue: SemanticIssue, now = new Date(), hints: MapHints = {}): IssueMap {
   const owners = new Map<string, string>();
   const childKeys = new Set(issue.children.map((child) => child.identifier.toUpperCase()));
+  const found = (text: string) => [
+    ...pathsIn(text).map((path) => hints.resolved?.get(path) ?? path),
+    ...areasIn(text, hints.areas ?? []).map((area) => area.path),
+  ];
   for (const child of issue.children) {
-    for (const path of pathsIn(child.title)) owners.set(path, child.identifier);
+    for (const path of found(child.title)) owners.set(path, child.identifier);
   }
   const lines = `${issue.title}\n${issue.description ?? ""}`.split("\n");
   for (const line of lines) {
     const named = (line.match(ISSUE_KEY) ?? []).find((key) => childKeys.has(key));
-    for (const path of pathsIn(line)) {
+    for (const path of found(line)) {
       if (!owners.has(path)) owners.set(path, named ?? issue.identifier);
     }
   }