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

package/OVERVIEW.md

@@ -39,9 +39,13 @@ In **Settings → Plugins → Linear → Icon**, choose an SVG file or paste SVG
 
 Turn on **Update Linear from agent todos** in the Live settings. After each turn, a todo that starts with a sub-issue key, such as `ENG-124: add the queue`, moves that sub-issue to In Progress, and then to Done when all its todos are done. The parent moves to In Review when every sub-issue is done, never to Done. Statuses only move forward.
 
+## Project knowledge
+
+The daemon keeps a map of each project's files without an agent: its folders, services, packages, languages, commands, and guide files. Explore and setup agents start from it. Ticket-text maps use it to match short paths to real files and to put a named service on the map. When an agent works off the map, Linear Live shows the service or folder it is in. See it, or inspect again, under **Project knowledge** in **Projects**.
+
 ## Set up project prompts
 
-In **Projects**, select **Start** under **Set up with an agent**. An agent reads the repository's guidelines, scripts, and CI files and proposes project instructions, steps, and prompt additions. You accept each change before it is saved.
+In **Projects**, select **Start** under **Set up with an agent**. An agent reads the repository's guidelines, scripts, and CI files and proposes project instructions, steps, and prompt additions. You accept each change before it is saved. **Open agent** shows the agent while it works, and the lines it writes about the project and its areas go into the project knowledge.
 
 ## Choose projects
 
@@ -53,4 +57,4 @@ Choose **Attach Linear issue** in the composer attachment menu. The agent gets t
 
 ## Data and permissions
 
-Only the daemon sends requests to `https://api.linear.app/graphql`. The daemon never sends a key back to the app. Paseo sends the prompt, with the issue snapshot, to the agent provider. Explore and setup agents read project files and send them to your agent provider. The daemon saves explore maps, and agents that wait for a map, beside the key file, and Linear Live lists and reads files only inside the agent's folder. For Claude agents, the daemon also reads the subagent transcripts Claude saves for the session, to show what each subagent does. With agent guidance on, it writes Claude Code hooks with the issue keys and titles beside the key file, and it serves the Linear tools on 127.0.0.1 with a token for each agent. Each token reaches only its issue and that issue's sub-issues. With todo sync on, the daemon changes issue statuses in Linear. The daemon keeps recent Linear responses in memory for up to 24 hours, and the list shows them with **Showing saved results. Updating…** while it gets new data.
+Only the daemon sends requests to `https://api.linear.app/graphql`. The daemon never sends a key back to the app. Paseo sends the prompt, with the issue snapshot, to the agent provider. Explore and setup agents read project files and send them to your agent provider. The daemon saves explore maps, project knowledge, and agents that wait for a map, beside the key file, and Linear Live lists and reads files only inside the agent's folder. For Claude agents, the daemon also reads the subagent transcripts Claude saves for the session, to show what each subagent does. With agent guidance on, it writes Claude Code hooks with the issue keys and titles beside the key file, and it serves the Linear tools on 127.0.0.1 with a token for each agent. Each token reaches only its issue and that issue's sub-issues. With todo sync on, the daemon changes issue statuses in Linear. The daemon keeps recent Linear responses in memory for up to 24 hours, and the list shows them with **Showing saved results. Updating…** while it gets new data.

package/README.md

@@ -156,16 +156,16 @@ The **Linear** screen in the sidebar is not tied to a project, so it stays avail
 Linear Live is an agent panel. Open it from the Linear pill, or with **Linear: Open Linear Live** in the command center while an agent is open. It works for agents started from an issue, with Claude, Codex, and other providers.
 
 - **Sub-issues:** each sub-issue shows its Linear status and the agent's todo progress. The todos of the current sub-issue show under it. Select a sub-issue to show only its files on the map. Hide the issues column with the button on the **Issue** card to give the map or the graph the full width. The column becomes a strip with the status of each issue. Select an issue there to show only its files.
-- **Map:** files are grouped by folder. The map marks the files the agent read, edited, or created, and the file it is on now. Files the agent touched but the map did not predict have a dashed border. A folder the agent listed or searched gets a solid border, and its header shows how many of its files the agent touched. Reads through the shell count too: `cat`, `sed -n`, `head`, `grep`, `rg`, `ls`, `find`, `git show`, and redirects to files.
-- **Graph:** the files and the links between them. A line joins two files when one imports the other, a Markdown or style file links to the other, `package.json` names it, or the text of one names the path of the other. This works for TypeScript and JavaScript (with `tsconfig` paths and workspace packages), Python, Go, Rust, Ruby, CSS and Sass, Markdown, HTML, and config files. Files of one folder sit together under the folder name and take the color of their sub-issue. The issue is in the center, with its sub-issues joined to the files the map gives them. The agent hovers over what it works on: the file it reads or edits, or the sub-issue whose todo it just started. When the work moves, it glides along the links to the next node, and the lines at that node take its color. New files join without moving the rest. Agents that this agent started get their own cursor when they work in the same folder or in a worktree of the same project. An agent with no file activity yet hovers over the sub-issue whose key starts its title. Running subagents circle the agent that started them. Select a sub-issue to show only its files. Select any node to see what it is and how many files it links to. Switch between **Map** and **Graph** on the card, or set the default in **Show files as** in the Live settings.
+- **Map:** files are grouped by folder. The map marks the files the agent read, edited, or created, and the file it is on now. Files the agent touched but the map did not predict have a dashed border. A folder the agent listed or searched gets a solid border, and its header shows how many of its files the agent touched. The header also names the service, package, or main folder the folder is in, from the [project knowledge](#project-knowledge). When the agent touches files the map did not predict, the line under the map tells where they are, such as `Off the map: billing-api · service (2), docs (1)`, and the **Now** line in the header shows **Off the map** with the place of the current file. Reads through the shell count too: `cat`, `sed -n`, `head`, `grep`, `rg`, `ls`, `find`, `git show`, and redirects to files.
+- **Graph:** the files and the links between them. A line joins two files when one imports the other, a Markdown or style file links to the other, `package.json` names it, or the text of one names the path of the other. This works for TypeScript and JavaScript (with `tsconfig` paths and workspace packages), Python, Go, Rust, Ruby, CSS and Sass, Markdown, HTML, and config files. Files of one folder sit together under the folder name and take the color of their sub-issue. The issue is in the center, with its sub-issues joined to the files the map gives them. The agent hovers over what it works on: the file it reads or edits, or the sub-issue whose todo it just started. When the work moves, it glides along the links to the next node, and the lines at that node take its color. New files join without moving the rest. Agents that this agent started get their own cursor when they work in the same folder or in a worktree of the same project. An agent with no file activity yet hovers over the sub-issue whose key starts its title. Running subagents circle the agent that started them. Select a sub-issue to show only its files. Select any node to see what it is, how many files it links to, and for an off-map file, the service or folder it is in. Switch between **Map** and **Graph** on the card, or set the default in **Show files as** in the Live settings.
 - **Graph view:** the icon buttons at the top right of the graph move the view. **Follow the running agents** zooms to the nodes the running agents work on and the files next to them, and moves with the agents. **Show the whole graph** zooms out. **Zoom out** and **Zoom in** change the zoom in steps. Scroll to zoom at the pointer, drag to move when zoomed in, or pinch on a touch screen. Each of these stops following. The lock button lets the wheel and drags scroll the page instead. Nodes, lines, and labels keep their size when you zoom, and more file names show when there is room. The graph keeps your follow and lock choices.
 - **Agents:** the agents that work under this agent. Paseo agents that this agent started show their status, their files, and their own markers on the map when they work in the same folder or in a worktree of the same project. Select one to open it. Subagents that run inside the provider, such as Claude's Agent tool, show their type, description, and status. For Claude, the daemon reads each subagent's transcript, also for subagents that run in the background, so a subagent shows what it does now, gets its own cursor, and adds its files to the map. Other providers do not send subagent file reads, so the map shows only the files named in the subagent's prompt.
 - **Activity:** the latest reads, edits, searches, and commands, with line counts and exit codes.
 
 The map comes from one of two sources. Choose it in **Settings → Plugins → Linear → Live**:
 
-- **Ticket text** (the default) finds file and folder paths in the issue title, description, and sub-issue titles. It costs nothing, but it finds only paths the issue names. Linear sends sub-issue titles but not their descriptions.
-- **Explore agent** maps the files first when you start an implement agent. It reads the repository and lists the files for each sub-issue. The implement agent starts when the map is ready, or with the ticket-text map if exploring fails. A saved map is used again, so each issue is explored once. The plugin archives the explore agent when it finishes. Choose its model and effort in the Live settings. A faster, cheaper model, such as Haiku, is usually enough. It lists up to 150 files.
+- **Ticket text** (the default) finds file and folder paths in the issue title, description, and sub-issue titles. It costs nothing, but it finds only paths the issue names. Linear sends sub-issue titles but not their descriptions. With project knowledge, a short path such as `queries.ts` becomes the one project file that ends with it, and a service or package that the text names, such as `billing-api` or "the billing service", puts its folder on the map. A plain folder counts only when the text calls it a folder, such as "the docs folder".
+- **Explore agent** maps the files first when you start an implement agent. It starts from the project map in the project knowledge, reads the repository, and lists the files for each sub-issue. The implement agent starts when the map is ready, or with the ticket-text map if exploring fails. A saved map is used again, so each issue is explored once. The plugin archives the explore agent when it finishes. Choose its model and effort in the Live settings. A faster, cheaper model, such as Haiku, is usually enough. It lists up to 150 files.
 
 The buttons on the map card control the saved map. **Read files and links again** reloads the map, the folder lists, and the links. **Build** or **Rebuild the map with the explore agent** starts an explore run now and replaces the saved map when it finishes. **Clear the saved map** deletes it, so the map uses the ticket text until the next explore run. You cannot clear a map while an explore run makes it.
 
@@ -199,9 +199,20 @@ Turn on **Update Linear from agent todos** in the Live settings. After each turn
 
 The daemon reads the issue from Linear before each sync, so a status you changed by hand counts. **Sync now** in the pill runs the same check at once.
 
+### Project knowledge
+
+The daemon keeps a map of each project's files, so explore and setup agents, ticket-text maps, and Linear Live know the project before an agent reads it. No agent runs for it, and it costs no provider usage. The daemon makes it the first time a project needs it: when you open the project in **Settings → Plugins → Linear → Projects**, open Linear Live for one of its agents, or start an explore or setup run. It makes it again when it is 6 hours old, and **Inspect again** under **Project knowledge** makes it at once.
+
+- **Files:** the files git tracks or would track, without ignored files. Outside a git repository, the daemon walks the folder and skips folders such as `node_modules`, `dist`, and `.git`. It keeps up to 20,000 paths, the shallow ones first.
+- **Areas:** services, packages, and main folders. A folder with a manifest such as `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, or a `.csproj` file is a package, named by the manifest. A folder with a `Dockerfile`, `Procfile`, `fly.toml`, or a similar file, a folder that a compose file builds, and a package under a folder such as `apps/` or `services/` is a service. Each top folder is an area too, and so is each subfolder of a top folder that holds 40% or more of the files. Folder names give a role, such as backend, frontend, tests, or docs. Manifests in fixture, example, and template folders do not count.
+- **Languages, commands, and guides:** file counts by language, the root package scripts and Makefile targets, and files that guide agents, such as `AGENTS.md`, `CLAUDE.md`, the README, CONTRIBUTING, and CI workflows.
+- **Summaries:** the setup agent adds one line about the project and one line about each area. They stay when the daemon makes the map again.
+
+The **Project knowledge** section in the Projects settings shows what the daemon found.
+
 ### Set up project prompts with an agent
 
-In **Settings → Plugins → Linear → Projects**, select **Start** under **Set up with an agent**. An agent reads the project's AGENTS.md, CLAUDE.md, CONTRIBUTING, README, scripts, and CI files. It then proposes project instructions, steps, and text to add to the Implement and Review prompts. Each change shows the current and proposed text. Turn off the ones you do not want, select **Use accepted changes**, and then save. Nothing changes until you save.
+In **Settings → Plugins → Linear → Projects**, select **Start** under **Set up with an agent**. The daemon makes the project knowledge again first, and the agent starts from that project map. While it runs, **Open agent** opens the setup agent so you can watch it. The agent reads the project's AGENTS.md, CLAUDE.md, CONTRIBUTING, README, scripts, and CI files. It then proposes project instructions, steps, and text to add to the Implement and Review prompts. Each change shows the current and proposed text. Turn off the ones you do not want, select **Use accepted changes**, and then save. Nothing changes until you save. The agent also describes the project and each area, and the daemon saves those lines to the project knowledge at once.
 
 ## Data and permissions
 
@@ -209,6 +220,7 @@ In **Settings → Plugins → Linear → Projects**, select **Start** under **Se
 - **Data sent to Linear:** queries for issues, teams, users, and comments, and the changes you make. When you start an agent with the options on, the plugin moves the issue to In Progress and assigns it to you.
 - **Data sent to the agent provider:** the prompt. It holds the template text and an issue snapshot: identifier, title, URL, team, status, priority, assignee, project, labels, parent, description, sub-issues, and links. It holds comments only when **Include comments in the prompt** is on. It also holds the project instructions and steps from the Projects settings. An attached issue sends the identifier, title, URL, status, priority, assignee, project, labels, and description.
 - **Linear Live and setup agents:** the explore agent gets the issue snapshot without comments, and both agents read files in the project. Your agent provider gets what they read. The map of an explore run is saved in `live-maps.json` beside the key file, for up to 200 issues. An agent that waits for a map is saved in `pending-launches.json` there until it starts. Linear Live lists files only in the folders it shows, and reads the files on the graph to find their links, inside the agent's own folder. It does not follow links that lead outside that folder. For a Claude agent with subagents, the daemon reads the tool calls in the subagent transcripts that Claude saves for that session. It sends the app only the tool names, file paths, and commands, never file text.
+- **Project knowledge:** the daemon lists the files of a Paseo project with `git ls-files`, or by walking the folder, and reads small manifest files (up to 256 KB) inside the project folder. It does not follow links that lead outside the folder. It saves file paths, manifest names, script names, and summaries in `knowledge/` beside the key file, one file per project. The app gets the areas, counts, commands, and guides, never the file list. Explore and setup prompts hold the project map: folder names with file counts, areas, commands, and guide file names. Your agent provider gets that text.
 - **Linear tools for agents:** the daemon runs the `linear` MCP server on `127.0.0.1` only, and only after an agent gets it. Each agent gets its own random token, and its tools reach only its issue and that issue's sub-issues. Edits use the Linear key of the project that loaded the issue. Requests from a web page are refused. `agent-tools.json` beside the key file keeps the port and a hash of each token, so agents keep their tools after a restart. The token itself is in the agent's Paseo config.
 - **Claude hooks:** when an **Agent guidance** switch is on for a Claude agent, the daemon writes a Claude Code plugin to `claude-hooks/` beside the key file, one folder for each issue and set of hooks. It holds the issue key and title and the sub-issue keys and titles. The agent starts with `--plugin-dir` set to that folder. The hooks print that text and run no other command. The daemon does not write hooks on Windows hosts.
 - **Todo sync:** when it is on, the daemon changes issue statuses in Linear with the key of the project that loaded the issue.
@@ -240,7 +252,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `client/live-map.tsx`, `client/live-graph.tsx`, `client/graph-labels.ts`, `client/graph-camera.tsx`, `client/live-cursor.tsx`, `client/live-agents.tsx` | App | File map, file graph with its labels and camera, agent cursors, and the agents list |
 | `client/tool-buttons.tsx`, `client/web.ts` | App | Icon buttons for the map and graph, and the wheel listener and file picker on the web |
 | `client/pill.tsx` | App | Linear pill in each agent's composer |
-| `client/project-init.tsx` | App | Project setup proposal in the Projects settings |
+| `client/project-init.tsx`, `client/project-knowledge.tsx` | App | Project setup proposal and the Project knowledge section in the Projects settings |
 | `shared/linear.ts` | Both | RPC contracts and issue schemas |
 | `shared/issues.ts` | Both | The `issues.search` RPC and the composer attachment source |
 | `shared/settings.ts` | Both | Settings schema: templates, agent defaults, and project settings |
@@ -252,6 +264,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `shared/agent-hooks.ts`, `server/agent-hooks.ts` | Both, Daemon | Claude Code hooks for agent guidance, and the plugin folder the daemon writes |
 | `shared/agent-tools.ts`, `server/agent-tools.ts`, `server/mcp-http.ts` | Both, Daemon | The `linear` MCP server: its tools, tokens, and HTTP transport |
 | `shared/todo-sync.ts`, `shared/project-setup.ts` | Both | Todo keys, status moves, and setup proposals |
+| `shared/knowledge.ts` | Both | Project knowledge contracts, areas and their labels, the project map for prompts, and ticket path matching |
 | `server/handlers.ts` | Daemon | RPC handlers, key lookup, and cache use |
 | `server/credentials.ts` | Daemon | Key file and key order |
 | `server/cache.ts` | Daemon | Response cache in memory |
@@ -259,6 +272,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `server/linear.ts` | Daemon | Search and snapshot text for the composer attachment |
 | `server/live.ts`, `server/links.ts`, `server/subagent-logs.ts`, `server/agent-runs.ts` | Daemon | File listing, links between files, subagent transcripts, explore runs, and the saved maps |
 | `server/sync.ts`, `server/init.ts` | Daemon | Todo sync after each turn, and project setup runs |
+| `server/inspect.ts`, `server/knowledge.ts` | Daemon | Project inspection without an agent, and the saved project knowledge |
 
 The client bundle holds no credentials and makes no calls to Linear.
 

package/client/live-graph.tsx

@@ -3,6 +3,7 @@ import { Animated, type LayoutChangeEvent, Pressable, StyleSheet, Text, View } f
 import { focusBox, project, unproject } from "../shared/graph-camera";
 import type { Placed, Point } from "../shared/graph-geometry";
 import { focusNode, type Graph, type GraphEdge, type GraphNode, graphKey, layoutGraph } from "../shared/graph-model";
+import { type AreaRef, whereLabel } from "../shared/knowledge";
 import type { IssueDetail, WorkflowState } from "../shared/linear";
 import type { GraphCamera } from "../shared/settings";
 import { CameraButtons, useGraphCamera } from "./graph-camera";
@@ -29,6 +30,8 @@ export interface GraphViewProps {
   progress: IssueProgress;
   owners: OwnerColors;
   agents: readonly CursorAgent[];
+  /** Areas of the project, to say where an off-map file is. */
+  areas: readonly AreaRef[];
   focus: string | null;
   onFocus(key: string): void;
   /** Saved camera mode: follow the running agents, or show the whole graph. */
@@ -223,7 +226,7 @@ const GraphNodeView = memo(function GraphNodeView(props: NodeProps) {
   );
 }, sameNode);
 
-function caption(node: GraphNode, issue: IssueDetail, graph: Graph): string {
+function caption(node: GraphNode, issue: IssueDetail, graph: Graph, areas: readonly AreaRef[]): string {
   if (node.kind === "issue") return `${issue.identifier} · ${issue.title}`;
   if (node.kind === "subissue") {
     const child = issue.children.find((entry) => entry.identifier.toUpperCase() === node.label);
@@ -231,7 +234,7 @@ function caption(node: GraphNode, issue: IssueDetail, graph: Graph): string {
     return `${node.label} · ${child?.state.name ?? ""} · ${child?.title ?? ""}${folded}`;
   }
   const tile = node.tile;
-  const where = tile?.onMap ? `on the map for ${node.owner}` : "not on the map";
+  const where = tile?.onMap ? `on the map for ${node.owner}` : `not on the map, in ${whereLabel(node.path ?? "", areas)}`;
   const touch = !tile || tile.touch === "none" ? "not touched yet" : tile.touch;
   const lines = tile && (tile.added > 0 || tile.removed > 0) ? ` · +${tile.added} -${tile.removed}` : "";
   const linked = graph.edges.filter((edge) => edge.kind !== "owns" && (edge.from === node.id || edge.to === node.id)).length;
@@ -507,7 +510,7 @@ export function LiveGraph(props: GraphViewProps) {
       <View style={styles.caption}>
         {selectedNode ? (
           <Text numberOfLines={2} style={styles.captionText}>
-            {caption(selectedNode, issue, graph)}
+            {caption(selectedNode, issue, graph, props.areas)}
           </Text>
         ) : (
           <Text style={styles.hint}>Select a node to see its file or issue.</Text>

package/client/live-header.tsx

@@ -79,7 +79,7 @@ function StatusChip(props: { theme: Theme; status: AgentStatus; provider: string
   );
 }
 
-function NowLine(props: { theme: Theme; event: ActivityEvent; live: boolean }) {
+function NowLine(props: { theme: Theme; event: ActivityEvent; live: boolean; offMap: string | null }) {
   const { theme, event } = props;
   const { colors } = theme;
   const tone = eventTone(theme, event);
@@ -106,6 +106,18 @@ function NowLine(props: { theme: Theme; event: ActivityEvent; live: boolean }) {
         tint: { ...StyleSheet.absoluteFillObject, borderRadius: 6, backgroundColor: tone, opacity: 0.14 },
         text: { color: props.live ? colors.foreground : colors.foregroundMuted, fontSize: 13 },
         detail: { flex: 1, color: colors.foregroundMuted, fontFamily: MONO, fontSize: 11 },
+        off: {
+          flexShrink: 0,
+          maxWidth: 220,
+          paddingHorizontal: 7,
+          paddingVertical: 2,
+          borderRadius: 6,
+          borderWidth: 1,
+          borderStyle: "dashed",
+          borderColor: colors.statusWarning,
+          color: colors.statusWarning,
+          fontSize: 11,
+        },
       }) as const,
     [colors, tone, props.live],
   );
@@ -124,6 +136,11 @@ function NowLine(props: { theme: Theme; event: ActivityEvent; live: boolean }) {
           {event.detail}
         </Text>
       ) : null}
+      {props.offMap ? (
+        <Text numberOfLines={1} style={styles.off} accessibilityLabel={`Off the map, in ${props.offMap}`}>
+          {`Off the map · ${props.offMap}`}
+        </Text>
+      ) : null}
     </View>
   );
 }
@@ -136,6 +153,8 @@ export function LiveHeader(props: {
   status: AgentStatus;
   provider: string;
   current: ActivityEvent | null;
+  /** Where the current file is when the agent works off the map. */
+  offMap: string | null;
   reduceMotion: boolean;
 }) {
   const { theme, issue, progress, owners } = props;
@@ -204,7 +223,12 @@ export function LiveHeader(props: {
       </View>
       {counts.length > 0 ? <Text style={styles.counts}>{counts.join(" · ")}</Text> : null}
       {props.current ? (
-        <NowLine theme={theme} event={props.current} live={props.status === "running"} />
+        <NowLine
+          theme={theme}
+          event={props.current}
+          live={props.status === "running"}
+          offMap={props.offMap}
+        />
       ) : null}
     </View>
   );

package/client/live-map.tsx

@@ -8,6 +8,7 @@ import {
   type MapZone,
   masonry,
   ZONE_GAP,
+  zoneAreaLabel,
 } from "../shared/map-model";
 import { NATIVE_DRIVER, type OwnerColors } from "./live-timeline";
 import type { AgentMarker } from "./live-agents";
@@ -197,7 +198,8 @@ function Zone(props: RepoMapProps & { zone: MapZone }) {
           opacity: 0.35,
         },
         header: { flexDirection: "row", alignItems: "center", gap: 6 },
-        dir: { flex: 1, color: colors.foregroundMuted, fontFamily: MONO, fontSize: 11 },
+        dir: { flexShrink: 1, color: colors.foregroundMuted, fontFamily: MONO, fontSize: 11 },
+        area: { flex: 1, color: colors.foregroundMuted, fontSize: 11, opacity: 0.8 },
         count: { color: hot ? colors.foreground : colors.foregroundMuted, fontSize: 11 },
         tiles: { flexDirection: "row", flexWrap: "wrap", gap: 6 },
       }) as const,
@@ -207,6 +209,7 @@ function Zone(props: RepoMapProps & { zone: MapZone }) {
   let count: string | null = null;
   if (zone.predicted > 0) count = `${zone.hits}/${zone.predicted}${off > 0 ? ` +${off} off` : ""}`;
   else if (off > 0) count = `${off} off the map`;
+  const area = zoneAreaLabel(zone);
   return (
     <View style={styles.zone}>
       {hot ? <View pointerEvents="none" style={styles.ring} /> : null}
@@ -219,6 +222,9 @@ function Zone(props: RepoMapProps & { zone: MapZone }) {
         <Text numberOfLines={1} style={styles.dir}>
           {zone.dir || "./"}
         </Text>
+        <Text numberOfLines={1} style={styles.area}>
+          {area ?? ""}
+        </Text>
         {count ? <Text style={styles.count}>{count}</Text> : null}
       </View>
       <View style={styles.tiles}>

package/client/live-panel.tsx

@@ -23,7 +23,7 @@ import {
   useMapModel,
   useReduceMotion,
 } from "./live-timeline";
-import { hitRateLine } from "../shared/map-model";
+import { hitRateLine, offMapLine, offMapWhere } from "../shared/map-model";
 import { useIssue } from "./queries";
 import { Button, EmptyState, errorMessage, IconButton, type Theme } from "./ui";
 
@@ -219,7 +219,10 @@ function LiveView(props: BodyProps & { issue: IssueDetail }) {
     provider: agent.provider,
     activity,
   });
-  const model = useMapModel(agentId, liveMap.map.files, agents.files, agents.dirs);
+  const model = useMapModel(agentId, liveMap.map.files, agents.files, agents.dirs, liveMap.areas);
+  const offMap = offMapLine(model);
+  const currentPath = activity.current?.path ?? null;
+  const where = useMemo(() => offMapWhere(model, currentPath, liveMap.areas), [model, currentPath, liveMap.areas]);
   // Hold the map until its first full data, so it does not draw once and then swap.
   const mapShown = useRef(false);
   if (liveMap.ready && model.ready) mapShown.current = true;
@@ -300,6 +303,7 @@ function LiveView(props: BodyProps & { issue: IssueDetail }) {
         main: { flex: 1, minWidth: 0 },
         mainContent: { gap: 16, paddingBottom: 32 },
         hit: { color: colors.foregroundMuted, fontSize: 12 },
+        off: { color: colors.statusWarning, fontSize: 12 },
         tools: { flexDirection: "row", alignItems: "center", gap: 12 },
         mapHead: { gap: 8 },
         mapWait: { minHeight: 240, alignItems: "center", justifyContent: "center" },
@@ -316,6 +320,7 @@ function LiveView(props: BodyProps & { issue: IssueDetail }) {
       status={agent.status}
       provider={agent.provider}
       current={activity.current}
+      offMap={where}
       reduceMotion={reduceMotion}
     />
   );
@@ -351,6 +356,7 @@ function LiveView(props: BodyProps & { issue: IssueDetail }) {
       ) : (
       <View style={styles.mapHead}>
         <Text style={styles.hit}>{hitRateLine(model)}</Text>
+        {offMap ? <Text style={styles.off}>{offMap}</Text> : null}
         {graph ? (
           <LiveGraph
             theme={theme}
@@ -362,6 +368,7 @@ function LiveView(props: BodyProps & { issue: IssueDetail }) {
             progress={progress}
             owners={owners}
             agents={cursors}
+            areas={liveMap.areas}
             focus={focus}
             onFocus={toggleFocus}
             camera={props.graphCamera}

package/client/live-timeline.ts

@@ -3,6 +3,7 @@ import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tansta
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { AccessibilityInfo, Platform } from "react-native";
 import type { DirTouch, FileTouch, TimelineItemLike } from "../shared/activity";
+import { type AreaRef, liveProjectRpc, MAX_RESOLVE_PATHS } from "../shared/knowledge";
 import type { IssueDetail } from "../shared/linear";
 import type { FileLink } from "../shared/links";
 import {
@@ -240,6 +241,8 @@ export function ownerColors(issue: IssueDetail, accent: string): OwnerColors {
 // runs, and slowly while there is no map, since a launch can start a job after this mounts.
 export interface LiveMap {
   map: IssueMap;
+  /** Services, packages, and main folders of the agent's project, from its saved knowledge. */
+  areas: readonly AreaRef[];
   stored: boolean;
   /** The stored map has been read once, so the map no longer swaps from the fallback. */
   ready: boolean;
@@ -282,13 +285,14 @@ export function useLiveMap(
   const refresh = useCallback(() => void queries.invalidateQueries({ queryKey: ["linear", "live"] }), [queries]);
   const clearMap = useRpc(clearMapRpc);
   const clear = useMutation({ mutationFn: () => clearMap({ agentId }), onSettled: refresh });
-  const fallback = useMemo(() => semanticMap(issue), [issue]);
+  const project = useProjectKnowledge(agentId, issue);
   const stored = query.data?.map ?? null;
   const failure = explore.error ?? clear.error ?? query.error;
   return {
-    map: stored ?? fallback,
+    map: stored ?? project.fallback,
+    areas: project.areas,
     stored: stored !== null,
-    ready: query.data !== undefined || query.isError,
+    ready: (query.data !== undefined || query.isError) && project.ready,
     job: query.data?.job ?? null,
     starting: explore.isPending,
     error: failure ? errorMessage(failure) : null,
@@ -299,6 +303,32 @@ export function useLiveMap(
   };
 }
 
+const NO_AREAS: readonly AreaRef[] = [];
+
+/** The project's areas, and the ticket-text map with its paths matched to real files. */
+function useProjectKnowledge(agentId: string, issue: IssueDetail) {
+  const read = useRpc(liveProjectRpc);
+  const base = useMemo(() => semanticMap(issue), [issue]);
+  const paths = useMemo(
+    () => base.files.map((file) => file.path).slice(0, MAX_RESOLVE_PATHS).sort(),
+    [base],
+  );
+  const query = useQuery({
+    queryKey: ["linear", "live", "project", agentId, paths],
+    queryFn: () => read({ agentId, paths }),
+    staleTime: 5 * 60_000,
+    // Without knowledge the map still works, so a failure shows it at once.
+    retry: false,
+  });
+  const { data } = query;
+  const fallback = useMemo(() => {
+    if (!data) return base;
+    const resolved = new Map(data.resolved.map((entry) => [entry.from, entry.to]));
+    return semanticMap(issue, new Date(base.createdAt), { resolved, areas: data.areas });
+  }, [issue, base, data]);
+  return { fallback, areas: data?.areas ?? NO_AREAS, ready: data !== undefined || query.isError };
+}
+
 const NO_LISTING: ReadonlyMap<string, readonly string[]> = new Map();
 
 export function useMapModel(
@@ -306,6 +336,7 @@ export function useMapModel(
   files: readonly MapFile[],
   touches: readonly FileTouch[],
   explored: readonly DirTouch[],
+  areas: readonly AreaRef[] = NO_AREAS,
 ): MapModel & { ready: boolean } {
   const list = useRpc(listFilesRpc);
   const dirs = useMemo(
@@ -325,8 +356,8 @@ export function useMapModel(
   }, [listing.data]);
   const ready = dirs.length === 0 || listing.data !== undefined || listing.isError;
   return useMemo(
-    () => ({ ...buildMapModel(files, touches, byDir, explored), ready }),
-    [files, touches, byDir, explored, ready],
+    () => ({ ...buildMapModel(files, touches, byDir, explored, areas), ready }),
+    [files, touches, byDir, explored, areas, ready],
   );
 }
 

package/client/project-init.tsx

@@ -6,7 +6,7 @@ import {
   SettingsSection,
   SettingsSwitch,
 } from "@getpaseo/plugin/client/ui";
-import { useMutation, useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { Text, View } from "react-native";
 import { initStartRpc, initStatusRpc } from "../shared/live";
@@ -17,6 +17,7 @@ import {
   proposalDiffs,
 } from "../shared/project-setup";
 import type { ProjectConfig } from "../shared/settings";
+import { knowledgeKey } from "./project-knowledge";
 import { Button, errorMessage, type Theme } from "./ui";
 
 // Setup runs on the daemon. Remember the job per project so leaving the screen keeps it.
@@ -26,8 +27,10 @@ export function ProjectSetup(props: {
   theme: Theme;
   config: ProjectConfig;
   change(patch: Partial<ProjectConfig>): void;
+  /** Opens the setup agent while it runs; absent on hosts without navigation. */
+  openAgent?: (agentId: string) => void;
 }) {
-  const { theme, config, change } = props;
+  const { theme, config, change, openAgent } = props;
   const start = useRpc(initStartRpc);
   const status = useRpc(initStatusRpc);
   const [jobId, setJobId] = useState(() => jobsByProject.get(config.projectId) ?? null);
@@ -47,6 +50,12 @@ export function ProjectSetup(props: {
   });
   const state = job.data?.job ?? null;
   const proposal = job.data?.proposal ?? null;
+  // The daemon saved the agent's area summaries; show them in Project knowledge.
+  const queries = useQueryClient();
+  const finished = state?.status === "done";
+  useEffect(() => {
+    if (finished) void queries.invalidateQueries({ queryKey: knowledgeKey(config.projectId) });
+  }, [finished, queries, config.projectId]);
   const diffs = useMemo(
     () => (proposal ? proposalDiffs(config, proposal) : []),
     [config, proposal],
@@ -76,12 +85,27 @@ export function ProjectSetup(props: {
       <SettingsCard>
         <SettingsAction
           label="Read this repository's guidelines"
-          hint="An agent reads AGENTS.md, CONTRIBUTING, scripts, and CI, then proposes instructions and steps. It is told not to edit. You review each change before it is used."
+          hint="The daemon inspects the project first, and the agent starts from that project map. The agent reads AGENTS.md, CONTRIBUTING, scripts, and CI, then proposes instructions and steps, and describes each area for Project knowledge. It is told not to edit. You review each prompt change before it is used."
           actionLabel={running ? "Reading…" : proposal ? "Run again" : "Start"}
           disabled={running || !config.rootPath}
           onPress={() => begin.mutate()}
         />
-        {running ? <SettingsRow label="The setup agent is reading the repository." /> : null}
+        {running ? (
+          <SettingsRow
+            label={state?.agentId ? "The setup agent is reading the repository." : "Inspecting the project…"}
+          >
+            {state?.agentId && openAgent ? (
+              <View style={ACTIONS_STYLE}>
+                <Button
+                  theme={theme}
+                  icon="Bot"
+                  label="Open agent"
+                  onPress={() => openAgent(state.agentId ?? "")}
+                />
+              </View>
+            ) : null}
+          </SettingsRow>
+        ) : null}
         {failure ? <SettingsRow label="Setup did not finish" error={failure} /> : null}
         {state?.status === "done" && diffs.length === 0 ? (
           <SettingsAction

package/client/project-knowledge.tsx

@@ -0,0 +1,87 @@
+import { useRpc } from "@getpaseo/plugin/client";
+import {
+  SettingsAction,
+  SettingsCard,
+  SettingsRow,
+  SettingsSection,
+} from "@getpaseo/plugin/client/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  areaLabel,
+  knowledgeGetRpc,
+  knowledgeInspectRpc,
+  MAX_KNOWLEDGE_FILES,
+  type ProjectBrief,
+} from "../shared/knowledge";
+import { errorMessage, relativeTime } from "./ui";
+
+const AREAS_SHOWN = 24;
+
+export const knowledgeKey = (projectId: string) => ["linear", "knowledge", projectId] as const;
+
+function countText(entries: readonly { name: string; files: number }[]): string {
+  return entries.map((entry) => `${entry.name} ${entry.files}`).join(", ");
+}
+
+function overview(brief: ProjectBrief): string {
+  const source = brief.source === "git" ? "files git tracks" : "files found in the folder";
+  const truncated = brief.truncated ? `; the first ${MAX_KNOWLEDGE_FILES.toLocaleString()} are kept` : "";
+  return `${brief.fileCount} ${source}${truncated}. Inspected ${relativeTime(brief.inspectedAt)}.`;
+}
+
+/** What the daemon knows about the project's files, and a button to inspect it again. */
+export function ProjectKnowledgeSection(props: { projectId: string }) {
+  const { projectId } = props;
+  const get = useRpc(knowledgeGetRpc);
+  const inspect = useRpc(knowledgeInspectRpc);
+  const queries = useQueryClient();
+  const query = useQuery({
+    queryKey: knowledgeKey(projectId),
+    queryFn: () => get({ projectId }),
+    staleTime: 60_000,
+    retry: false,
+  });
+  const again = useMutation({
+    mutationFn: () => inspect({ projectId }),
+    onSuccess: (data) => queries.setQueryData(knowledgeKey(projectId), data),
+  });
+  const brief = query.data?.knowledge ?? null;
+  const busy = query.isPending || again.isPending;
+  const failure = again.error ?? query.error;
+  const areas = brief?.areas.filter((area) => area.path !== "") ?? [];
+  return (
+    <SettingsSection title="Project knowledge">
+      <SettingsCard>
+        <SettingsAction
+          label="Inspect the project"
+          hint="The daemon lists the project's files and reads its manifests to find its services, packages, and main folders. No agent runs. Explore and setup agents, ticket-text maps, and Linear Live use what it finds. It inspects again when the knowledge is 6 hours old."
+          actionLabel={busy ? "Inspecting…" : "Inspect again"}
+          disabled={busy}
+          onPress={() => again.mutate()}
+        />
+        {failure ? <SettingsRow label="Inspection did not finish" error={errorMessage(failure)} /> : null}
+        {brief ? (
+          <>
+            <SettingsRow label="Files" hint={overview(brief)} />
+            {brief.summary ? <SettingsRow label="Project" hint={brief.summary} /> : null}
+            {brief.languages.length > 0 ? (
+              <SettingsRow label="Languages" hint={countText(brief.languages)} />
+            ) : null}
+            {brief.commands.length > 0 ? (
+              <SettingsRow label="Commands" hint={brief.commands.join(", ")} />
+            ) : null}
+            {brief.guides.length > 0 ? <SettingsRow label="Guides" hint={brief.guides.join(", ")} /> : null}
+            {areas.slice(0, AREAS_SHOWN).map((area) => {
+              const files = `${area.files} ${area.files === 1 ? "file" : "files"}`;
+              const parts = [areaLabel(area), files, area.languages.join("/"), area.summary];
+              return <SettingsRow key={area.path} label={area.path} hint={parts.filter(Boolean).join(" · ")} />;
+            })}
+            {areas.length > AREAS_SHOWN ? (
+              <SettingsRow label={`${areas.length - AREAS_SHOWN} more areas`} />
+            ) : null}
+          </>
+        ) : null}
+      </SettingsCard>
+    </SettingsSection>
+  );
+}

package/client/settings-projects.tsx

@@ -22,6 +22,7 @@ import {
 } from "../shared/settings";
 import { effectiveKeyScope, KeyScopeProvider } from "./key-scope";
 import { ProjectSetup } from "./project-init";
+import { ProjectKnowledgeSection } from "./project-knowledge";
 import { AccessSection } from "./settings-access";
 import { type PaseoProjectOption, useAuthStatus, useCatalog, useProjects } from "./queries";
 import {
@@ -42,11 +43,15 @@ const STEPS_PLACEHOLDER = "Run the type checker\nUpdate the changelog\nOpen a dr
 
 type Change = (patch: Partial<ProjectConfig>) => void;
 
-export function ProjectSettings({ theme }: PluginSurfaceProps) {
+export function ProjectSettings({ theme, navigation }: PluginSurfaceProps) {
   const settings = useSettings(linearSettings);
+  const openAgent = useMemo(
+    () => (navigation ? (agentId: string) => navigation.openAgent({ agentId }) : undefined),
+    [navigation],
+  );
   const render = useCallback(
-    (ready: ReadySettings) => <ProjectEditor theme={theme} settings={ready} />,
-    [theme],
+    (ready: ReadySettings) => <ProjectEditor theme={theme} settings={ready} openAgent={openAgent} />,
+    [theme, openAgent],
   );
   return (
     <SettingsGate theme={theme} title="Projects" settings={settings}>
@@ -72,7 +77,12 @@ function projectOptions(
   return [...known, ...missing];
 }
 
-function ProjectEditor({ theme, settings }: { theme: Theme; settings: ReadySettings }) {
+function ProjectEditor(props: {
+  theme: Theme;
+  settings: ReadySettings;
+  openAgent?: (agentId: string) => void;
+}) {
+  const { theme, settings } = props;
   const { values, dirty, edit, save, discard } = useSettingsDraft(settings);
   const projects = useProjects();
   const [selectedId, setSelectedId] = useState<string | null>(null);
@@ -140,7 +150,8 @@ function ProjectEditor({ theme, settings }: { theme: Theme; settings: ReadySetti
         </SettingsCard>
       </SettingsSection>
       <TeamsSection config={config} change={change} />
-      <ProjectSetup theme={theme} config={config} change={change} />
+      {paseoProject ? <ProjectKnowledgeSection projectId={paseoProject.projectId} /> : null}
+      <ProjectSetup theme={theme} config={config} change={change} openAgent={props.openAgent} />
       <InstructionsSection theme={theme} config={config} change={change} />
       {AGENT_ACTIONS.map((action) => (
         <ActionSection key={action} theme={theme} action={action} config={config} change={change} />

package/index.server.ts

@@ -5,6 +5,7 @@ import { registerAgentTools } from "./server/agent-tools";
 import { createCredentialStore, defaultCredentialPath } from "./server/credentials";
 import { registerHandlers } from "./server/handlers";
 import { registerInit } from "./server/init";
+import { createKnowledge, registerKnowledge } from "./server/knowledge";
 import { registerLive } from "./server/live";
 import { createLaunchQueue, createMapStore } from "./server/stores";
 import { registerSync } from "./server/sync";
@@ -23,9 +24,11 @@ export default function contribute(server: PluginServerContext) {
   const dataDirectory = path.dirname(credentialPath);
   const maps = createMapStore(path.join(dataDirectory, "live-maps.json"));
   const launches = createLaunchQueue(path.join(dataDirectory, "pending-launches.json"));
-  registerLive(server, { access, maps, launches, readSettings });
+  const knowledge = createKnowledge(path.join(dataDirectory, "knowledge"));
+  registerKnowledge(server, knowledge);
+  registerLive(server, { access, maps, launches, knowledge, readSettings });
   registerSync(server, { access, readSettings });
-  registerInit(server, { readSettings });
+  registerInit(server, { readSettings, knowledge });
   registerAgentHooks(server, dataDirectory);
   const closeTools = registerAgentTools(server, { access, dataDirectory });
   server.handle(accessRpc, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "1.1.0-beta.2",
+  "version": "1.1.0-beta.3",
   "description": "Browse and triage Linear issues in Paseo and start agents from them",
   "license": "Apache-2.0",
   "type": "module",