papilot 0.1.1 → 0.2.0

package/dist/index.html

@@ -1,4 +1,13 @@
 <!doctype html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, interactive-widget=resizes-content"/><meta name="theme-color" content="#ffffff"/><meta name="description" content="Revise LaTeX papers with an agent and review the PDF changes."/><link rel="icon" type="image/png" href="/favicon.png"/><link rel="apple-touch-icon" href="/apple-touch-icon.png"/><title>Papilot</title>  <script type="module" crossorigin src="/assets/index-BhQFCMTx.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-CAV3-87U.css">
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, interactive-widget=resizes-content"/><meta name="theme-color" content="#ffffff"/><meta name="description" content="Revise LaTeX papers with an agent and review the PDF changes."/><link rel="icon" type="image/png" href="/favicon.png"/><link rel="apple-touch-icon" href="/apple-touch-icon.png"/><title>Papilot</title><script>
+// Resolve before the first paint, even while the application bundle is loading.
+(() => {
+  let theme;
+  try { theme = localStorage.getItem('papilot:theme'); } catch {}
+  const dark = theme === 'dark' || (theme !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches);
+  document.documentElement.dataset.theme = dark ? 'dark' : 'light';
+  document.querySelector('meta[name="theme-color"]').content = dark ? '#26272b' : '#ffffff';
+})();
+</script><style>html{--lightningcss-light:initial;--lightningcss-dark: ;color-scheme:light;background:#fff}html[data-theme=dark]{--lightningcss-light: ;--lightningcss-dark:initial;color-scheme:dark;background:#26272b}</style>  <script type="module" crossorigin src="/assets/index-Czf1eCno.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-CqhlgnOu.css">
 </head><body><div id="root"></div></body></html>

package/examples/papilot-paper/preamble.tex

@@ -18,17 +18,23 @@
 \usepackage[colorlinks=true,linkcolor=blue!50!black,citecolor=blue!50!black,urlcolor=blue!50!black]{hyperref}
 \usepackage[nameinlink]{cleveref}
 
-% thmtools lets cleveref name each kind of statement correctly although they
-% share one counter.
-\usepackage{thmtools}
-\declaretheorem[style=plain, numberwithin=section]{theorem}
-\declaretheorem[style=plain, sibling=theorem]{proposition}
-\declaretheorem[style=plain, sibling=theorem]{lemma}
-\declaretheorem[style=plain, sibling=theorem]{corollary}
-\declaretheorem[style=definition, sibling=theorem]{definition}
-\declaretheorem[style=definition, sibling=theorem]{example}
-\declaretheorem[style=definition, sibling=theorem]{assumption}
-\declaretheorem[style=remark, sibling=theorem]{remark}
+% Every kind of statement shares the theorem counter, and cleveref still names
+% each kind correctly. LaTeX from June 2026 does this itself and clashes with
+% thmtools, which older LaTeX needs for it.
+\IfFormatAtLeastTF{2026-06-01}
+  {\newtheorem{theorem}{Theorem}[section]
+   \NewDocumentCommand\statement{mmm}{\theoremstyle{#1}\newtheorem{#2}[theorem]{#3}}}
+  {\usepackage{thmtools}
+   \declaretheorem[style=plain, numberwithin=section]{theorem}
+   \NewDocumentCommand\statement{mmm}{\declaretheorem[style=#1, sibling=theorem, name=#3]{#2}}}
+\statement{plain}{proposition}{Proposition}
+\statement{plain}{lemma}{Lemma}
+\statement{plain}{corollary}{Corollary}
+\statement{definition}{definition}{Definition}
+\statement{definition}{example}{Example}
+\statement{definition}{assumption}{Assumption}
+\statement{remark}{remark}{Remark}
+\crefname{assumption}{assumption}{assumptions}
 \numberwithin{equation}{section}
 
 \newcommand{\R}{\mathbb{R}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papilot",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A Cursor-like workspace for your papers: annotate and review PDFs directly without ever touching LaTeX.",
   "keywords": [
     "latex",
@@ -35,6 +35,8 @@
     "src/server",
     "src/shared.ts",
     "src/notes.ts",
+    "src/conversation.ts",
+    "skills",
     "dist",
     "scripts/demo.ts",
     "scripts/service.ts",
@@ -56,9 +58,12 @@
     "test": "tsx --test tests/*.test.ts",
     "setup:review": "npm --prefix vendor/latex-review ci && npm --prefix vendor/latex-review run build",
     "demo": "tsx scripts/demo.ts",
+    "doctor": "node bin/papilot.mjs doctor",
     "service:install": "tsx scripts/service.ts install",
     "service:stop": "tsx scripts/service.ts stop",
-    "test:ui": "npm run build && node scripts/check-ui.mjs",
+    "test:ui": "npm run build && node scripts/check-ui.mjs && node scripts/check-review-notes.mjs && node --import tsx scripts/check-review-flow.mjs && node scripts/check-skills.mjs",
+    "site": "node scripts/build-site.mjs",
+    "site:video": "node scripts/build-site.mjs --video",
     "prepack": "npm run build && npm run setup:review"
   },
   "dependencies": {
@@ -78,9 +83,14 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.2",
+    "katex": "^0.16.47",
     "pdfjs-dist": "^6.4.299",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
     "typescript": "^7.0.2",
     "vite": "^8.3.5"
   }

package/scripts/service.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { ROOT, DATA } from '../src/server/paths.ts';
+import { serviceEnvironment } from '../src/server/service-environment.ts';
 
 if (process.platform !== 'darwin') throw new Error('This service installer is for macOS. On other systems run npm start with your process manager.');
 const label = 'local.papilot';
@@ -14,8 +15,13 @@ if (process.argv[2] === 'stop') {
   const xml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
   fs.mkdirSync(DATA, { recursive: true, mode: 0o700 });
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  const env: Record<string, string> = { PATH: [path.join(ROOT, 'node_modules/.bin'), '/Library/TeX/texbin', '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'].join(':'), HOME: os.homedir(), NODE_ENV: 'production' };
-  for (const [key, value] of Object.entries(process.env)) if (key.startsWith('PAPILOT_') && value) env[key] = value;
+  let previous: NodeJS.ProcessEnv = {};
+  if (fs.existsSync(file)) {
+    try {
+      previous = JSON.parse(execFileSync('/usr/bin/plutil', ['-extract', 'EnvironmentVariables', 'json', '-o', '-', file], { encoding: 'utf8' }));
+    } catch { /* An older or incomplete plist may not contain environment settings. */ }
+  }
+  const env = serviceEnvironment(ROOT, os.homedir(), process.execPath, process.env, previous);
   const args = ['/usr/bin/caffeinate', '-i', process.execPath, '--import', 'tsx', path.join(ROOT, 'src/server/main.ts')];
   const plist = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>
 <key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${args.map(a => `<string>${xml(a)}</string>`).join('')}</array>

package/skills/check-math.md

@@ -0,0 +1,12 @@
+---
+name: Check math
+description: Find errors in notation, equations and proofs
+hint: Which part? e.g. "Section 3 and Appendix A". Leave empty for the whole paper
+order: 4
+---
+Check the mathematics for errors and inconsistencies.
+
+- Every symbol is defined before it is used and means one thing throughout. Indices, signs, dimensions and quantifiers agree. Theorem statements match their proofs and the places that cite them. References to equations, theorems and figures point to the right ones.
+- Fix clear slips directly: a typo in a formula, an inconsistent symbol, a wrong reference.
+- Do not change what a result says. If you suspect a substantive error, leave the text and explain the problem in your summary, with its location and your reasoning.
+- Follow the paper's own macros and environments.

package/skills/consistency.md

@@ -0,0 +1,11 @@
+---
+name: Consistency
+description: Unify terms, notation, spelling and references
+hint: Which part? Leave empty for the whole paper
+order: 5
+---
+Make the paper consistent with itself.
+
+- Terminology, capitalization and hyphenation; American or British spelling; acronyms defined once at first use and used after that; notation and macros; reference style (for example `\cref` or `Section~\ref`); numbers, units, list and caption punctuation.
+- For each difference, use the variant the paper uses most, and name your choices in the summary.
+- Do not change meaning, and leave quoted material and bibliography entries as they are.

package/skills/latex-warnings.md

@@ -0,0 +1,12 @@
+---
+name: Fix LaTeX warnings
+description: Resolve undefined references, overfull boxes and other build warnings
+hint: Anything to leave alone? Leave empty to fix every warning you can
+order: 6
+---
+Fix the problems LaTeX reports when it builds the paper.
+
+- Compile in your worktree (for example with `latexmk`) and read the log. If you cannot run commands, look for the same problems in the source instead.
+- Fix undefined or duplicate labels, references and citations; overfull boxes, by rewording slightly or allowing a break where the line overflows; and package warnings that point to real mistakes.
+- Do not silence warnings globally: no document-wide `\sloppy`, badness or tolerance changes, and no new packages, unless the request asks for them.
+- In your summary, list the warnings you fixed and any you left, with the reason.

package/skills/polish.md

@@ -0,0 +1,13 @@
+---
+name: Polish
+description: Improve clarity and flow, keeping the meaning
+hint: Which part? e.g. "the introduction". Leave empty for the whole paper
+order: 1
+---
+Improve the clarity, concision and flow of the prose, sentence by sentence and paragraph by paragraph.
+
+- Keep every claim, number, citation, label, definition and technical term. Do not add claims, results or citations.
+- Prefer concrete subjects and active verbs. Cut filler such as "it is worth noting that" or "in order to".
+- Keep the author's voice and the paper's terminology; never replace a defined term with a synonym.
+- Make the smallest edit that fixes a real problem, and leave sentences that already read well.
+- Do not touch mathematics, code, labels or the document's structure unless the request asks for it.

package/skills/proofread.md

@@ -0,0 +1,12 @@
+---
+name: Proofread
+description: Fix typos, grammar and punctuation without rewording
+hint: Which part? Leave empty for the whole paper
+order: 2
+---
+Proofread the prose for typos, spelling, grammar, punctuation, agreement, articles and repeated words.
+
+- Change only what is wrong. Do not rephrase correct sentences, reorder content, or change terminology, notation, citations or labels.
+- Keep the paper's spelling convention (American or British) as the majority of the text uses it.
+- Leave mathematics, code, citation keys, labels and URLs as they are.
+- In your summary, list anything you noticed but left because it needs the author's judgment.

package/skills/reviewer-response.md

@@ -0,0 +1,11 @@
+---
+name: Address reviewers
+description: Revise for reviewer comments and draft a point-by-point reply
+hint: Paste the reviewer comments
+order: 7
+---
+Revise the paper in response to the reviewer comments in the request.
+
+- For each comment, make a targeted change where one is warranted. Keep the rest of the text as it is.
+- Do not invent experiments, results or citations. When a comment needs new work, say so in the reply instead of editing.
+- End with a point-by-point reply in your summary: quote each comment briefly, then say what changed and where (section, and the new wording if it is short), or explain politely why nothing changed.

package/skills/shorten.md

@@ -0,0 +1,12 @@
+---
+name: Shorten
+description: Cut length without losing content
+hint: What and by how much? e.g. "Section 4 by a third" or "fit in 8 pages"
+order: 3
+---
+Make the text shorter while keeping its content.
+
+- Cut redundancy, repeated motivation, hedging and wordy phrasing first; merge sentences that say the same thing.
+- Keep every result, definition, theorem, figure, table and citation unless the request says otherwise.
+- With a page target, compile in your worktree to check the page count if you can run commands.
+- In your summary, say roughly how much you cut, what kind of text went, and what you considered cutting but kept.

package/src/conversation.ts

@@ -0,0 +1,37 @@
+import type { FeedbackSummary } from './shared.ts';
+
+// What the agent receives when the author sends review feedback without a
+// message of their own. The chat shows the feedback, never this prompt.
+export const reviewInstructions = 'Continue this task using the decisions and comments from this review round. Preserve accepted changes and do not reintroduce rejected edits. Address any remaining revision requests; if no revision is needed, summarize the result.';
+// Earlier versions stored the prompt itself as the author's message.
+export const isFeedbackPrompt = (text: string) => text === reviewInstructions || text === 'Address the comments from this review round. Preserve accepted changes and do not reintroduce rejected edits.';
+
+// A skill is a named set of instructions; the author's own words, if any, say where and how.
+export function skillPrompt(skill: { name: string; body: string; folder?: string }, request: string) {
+  return [
+    `Use the "${skill.name}" skill below for this request.${skill.folder ? ` Files the skill mentions are in ${skill.folder}.` : ''}`,
+    `<skill name="${skill.name}">\n${skill.body.trim()}\n</skill>`,
+    request.trim() ? `Request: ${request.trim()}` : 'No further details were given: apply the skill to the whole paper.',
+  ].join('\n\n');
+}
+
+interface FeedbackItem { kind?: string; round?: number | null; text?: string; changes?: (string | { file?: string; lines?: [number, number] })[] }
+// The review engine's feedback (see vendor/latex-review FeedbackItem) as the chat shows it.
+export function summarizeFeedback(feedback: { feedback?: FeedbackItem[]; build_error?: unknown }): FeedbackSummary | undefined {
+  const items = feedback.feedback || [];
+  if (!items.length && !feedback.build_error) return undefined;
+  const summary: FeedbackSummary = { round: null, accepted: 0, rejected: 0, undone: 0, comments: [], ...(feedback.build_error ? { buildError: true } : {}) };
+  for (const item of items) {
+    if (item.round) summary.round = Math.max(summary.round || 0, item.round);
+    const changes = item.changes || [];
+    if (item.kind === 'accept') summary.accepted += changes.length || 1;
+    else if (item.kind === 'reject') summary.rejected += changes.length || 1;
+    else if (item.kind === 'undo') summary.undone++;
+    else if ((item.kind === 'comment' || item.kind === 'note') && item.text?.trim()) {
+      const first = changes.find(change => typeof change === 'object' && change.file) as { file: string; lines?: [number, number] } | undefined;
+      const where = first ? `${first.file}${first.lines ? `:${first.lines[0]}` : ''}${changes.length > 1 ? ` +${changes.length - 1}` : ''}` : item.kind === 'note' ? 'Note on the review' : `Round ${item.round ?? ''}`.trim();
+      summary.comments.push({ where, text: item.text.trim().slice(0, 2000) });
+    }
+  }
+  return summary;
+}

package/src/notes.ts

@@ -7,6 +7,11 @@ const QUOTE = '   PDF text: "', REGION = '   Marked region: a figure, equation o
 
 export interface NoteSummary { where: string; quote: string; comment: string }
 
+export function reviewNotesInstructions(notes: NoteSummary[]) {
+  const items = notes.map((note, index) => `${index + 1}. ${note.where}\n${note.quote ? `${QUOTE}${note.quote}"` : REGION}${NOTE}${note.comment.trim().replace(/\n/g, '\n   ')}`);
+  return `${PREAMBLE} These notes refer to the displayed review round and its Before, After or Unchanged text. Region coordinates are percentages of the displayed PDF strip (left, top, right, bottom); any quoted text for a region is nearby context. Read the current source before editing. Preserve accepted changes and do not reintroduce rejected edits unless a note explicitly asks for it.\n\n${items.join('\n\n')}`;
+}
+
 export function notesInstructions(notes: Annotation[]) {
   const items = notes.map((note, index) => {
     const where = [`Page ${note.page + 1}`, note.source ? `${note.source.file} ${note.source.lines[0] === note.source.lines[1] ? `line ${note.source.lines[0]}` : `lines ${note.source.lines[0]}–${note.source.lines[1]}`}` : ''].filter(Boolean).join(' · ');

package/src/server/agents.ts

@@ -139,10 +139,11 @@ export class ClaudeAgent extends Adapter {
       this.ready = true;
     } finally { finish(); probe.close(); }
   }
-  // Claude tasks need an API key (or a cloud provider's own credentials):
-  // Anthropic does not accept a Claude subscription login through the SDK.
+  // Claude tasks need an API key, an ANTHROPIC_AUTH_TOKEN (for a gateway or an
+  // Anthropic-compatible ANTHROPIC_BASE_URL), or a cloud provider's own
+  // credentials: Anthropic does not accept a Claude subscription login through the SDK.
   protected account() {
-    const account = this.info.account, keyed = Boolean(account?.apiKeySource && !['none', 'oauth'].includes(account.apiKeySource));
+    const account = this.info.account, keyed = Boolean(account?.apiKeySource && !['none', 'oauth'].includes(account.apiKeySource)) || account?.tokenSource === 'ANTHROPIC_AUTH_TOKEN';
     const external = Boolean(account?.apiProvider && account.apiProvider !== 'firstParty');
     if (keyed || external) return { account: { email: account?.email, type: external ? account!.apiProvider : 'API key' }, requiresOpenaiAuth: false };
     return { account: null, requiresOpenaiAuth: true, reason: CLAUDE_KEY };

package/src/server/main.ts

@@ -11,6 +11,7 @@ import { reviewClient, allowedReviewRoute, rewriteReviewHtml, rewriteReviewJson,
 import { authorize } from './security.ts';
 import { fullPaperPdf } from './pdf.ts';
 import { Manuscripts, annotationTask, gitCommit, gitDiff, gitRemote, gitStatus } from './manuscript.ts';
+import { findSkill, listedSkill, loadSkills } from './skills.ts';
 import type { AgentId } from '../shared.ts';
 
 const store = new Store(path.join(DATA, 'papilot.sqlite'));
@@ -46,9 +47,14 @@ const effort = (value: unknown) => typeof value === 'string' && /^[a-z]{1,16}$/.
 const string = (value: unknown, name: string, max = 20000) => { if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(`${name} is required and must be no longer than ${max} characters.`); return value.trim(); };
 app.post('/api/projects', async request => { const b = request.body as any; return workspace.addProject(string(b.path, 'Repository path', 4000), b.name ? string(b.name, 'Paper name', 120) : undefined); });
 app.post<{ Params: { id: string } }>('/api/projects/:id/rename', request => workspace.renameProject(request.params.id, string((request.body as any).name, 'Paper name', 120)));
+// A skill's name: what the author typed after "/".
+const skillName = (value: unknown) => typeof value === 'string' && /^[a-z0-9][a-z0-9-]{0,47}$/.test(value) ? value : undefined;
+// Text the author may leave empty when a skill or review feedback says enough.
+const optional = (value: unknown, name: string) => value === undefined || value === '' ? '' : string(value, name);
+app.get<{ Params: { id: string } }>('/api/projects/:id/skills', request => ({ skills: loadSkills(store.project(request.params.id).path).map(listedSkill) }));
 app.post('/api/tasks', async request => {
-  const b = request.body as any;
-  return workspace.createTask({ id: string(b.id, 'Task ID', 64), projectId: string(b.projectId, 'Paper ID', 64), title: string(b.title, 'Task title', 120), instructions: string(b.instructions, 'Instructions'), agent: agent(b.agent), model: typeof b.model === 'string' ? b.model : undefined, effort: effort(b.effort) });
+  const b = request.body as any, skill = skillName(b.skill);
+  return workspace.createTask({ id: string(b.id, 'Task ID', 64), projectId: string(b.projectId, 'Paper ID', 64), title: string(b.title, 'Task title', 120), instructions: skill ? optional(b.instructions, 'Instructions') : string(b.instructions, 'Instructions'), skill, agent: agent(b.agent), model: typeof b.model === 'string' ? b.model : undefined, effort: effort(b.effort) });
 });
 app.get<{ Params: { id: string } }>('/api/tasks/:id/items', request => { store.task(request.params.id); return { items: store.items(request.params.id) }; });
 app.get<{ Params: { id: string }; Querystring: { round?: string; version?: string; download?: string } }>('/api/tasks/:id/pdf', async (request, reply) => {
@@ -61,8 +67,10 @@ app.get<{ Params: { id: string }; Querystring: { round?: string; version?: strin
   return reply.type('application/pdf').header('Content-Disposition', `${request.query.download === '1' ? 'attachment' : 'inline'}; filename="${filename}"`).sendFile(path.basename(pdf), path.dirname(pdf), { cacheControl: false });
 });
 app.post<{ Params: { id: string } }>('/api/tasks/:id/messages', async request => {
-  const b = request.body as any;
-  return workspace.enqueue(request.params.id, string(b.text, 'Revision instructions'), string(b.requestKey, 'Request ID', 100), true);
+  const b = request.body as any, task = store.task(request.params.id), feedback = b.feedback === true, name = skillName(b.skill);
+  const skill = name ? findSkill(store.project(task.projectId).path, name) : undefined;
+  const text = feedback || skill ? optional(b.text, 'Revision instructions') : string(b.text, 'Revision instructions');
+  return workspace.enqueue(task.id, text, string(b.requestKey, 'Request ID', 100), true, { skill, feedback });
 });
 app.post<{ Params: { id: string } }>('/api/tasks/:id/rename', request => workspace.renameTask(request.params.id, string((request.body as any).title, 'Task title', 120)));
 app.post<{ Params: { id: string } }>('/api/tasks/:id/interrupt', request => workspace.interrupt(request.params.id).then(() => ({ ok: true })));
@@ -193,7 +201,13 @@ await app.listen({ host: '127.0.0.1', port: PORT });
 store.recover();
 console.log(`Papilot is running at http://127.0.0.1:${PORT}${PUBLIC_ORIGIN ? `\nRemote: ${PUBLIC_ORIGIN}` : ''}`);
 void workspace.connect();
-for (const task of store.tasks().filter(t => t.status === 'building')) { store.updateTask(task.id, { status: 'interrupted', error: 'The server restarted during the PDF build. Check the review and rebuild it if needed.' }); void workspace.refresh(task.id); }
+// Recompute cached feedback counts, including decisions from before this restart.
+for (const task of store.tasks()) {
+  if (task.status === 'building') {
+    store.updateTask(task.id, { status: 'interrupted', error: 'The server restarted during the PDF build. Check the review and rebuild it if needed.' });
+    void workspace.refresh(task.id);
+  } else if (task.review?.round && task.status !== 'deleting') void workspace.refresh(task.id);
+}
 let shuttingDown = false;
 for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
   if (shuttingDown) return; shuttingDown = true; workspace.close();

package/src/server/review.ts

@@ -34,7 +34,7 @@ export function annotateReviewState(value: unknown, tasks: readonly Task[]): unk
   else if (task.status === 'building') decisionLock = 'Wait for the PDF build before accepting, rejecting, or undoing changes. You can still add comments.';
   else if (['running', 'waiting_input', 'queued'].includes(task.status)) decisionLock = 'Pause this task in Papilot before accepting, rejecting, or undoing changes. You can still add comments.';
   else if (task.pendingReview) decisionLock = 'Wait for the current review action before accepting, rejecting, or undoing changes. You can still add comments.';
-  return { ...state, decisionLock, commentLock };
+  return { ...state, decisionLock, commentLock, ...(task ? { workspace: { status: task.status, unsent: task.review?.unsent ?? 0, comments: task.review?.comments ?? 0, accepted: task.review?.files?.length ?? 0 } } : {}) };
 }
 
 export function allowedReviewRoute(route: string, method: string): boolean {

package/src/server/service-environment.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+
+/** launchd has no login shell. Keep the tool choices made by the installer. */
+export function serviceEnvironment(
+  root: string, home: string, executable: string,
+  inherited: NodeJS.ProcessEnv, previous: NodeJS.ProcessEnv = {},
+): Record<string, string> {
+  // An explicit empty value clears a previously saved override.
+  const toolPath = inherited.PAPILOT_SERVICE_PATH ?? previous.PAPILOT_SERVICE_PATH ?? '';
+  const directories = [
+    ...toolPath.split(path.delimiter),
+    path.dirname(executable), path.join(root, 'node_modules/.bin'),
+    ...(inherited.PATH || '').split(path.delimiter),
+    '/Library/TeX/texbin', '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin',
+  ].filter(directory => path.isAbsolute(directory));
+  const env: Record<string, string> = {
+    PATH: [...new Set(directories)].join(path.delimiter), HOME: home, NODE_ENV: 'production',
+  };
+  for (const [key, value] of Object.entries(inherited)) if (key.startsWith('PAPILOT_') && value) env[key] = value;
+  if (toolPath) env.PAPILOT_SERVICE_PATH = toolPath;
+  return env;
+}

package/src/server/skills.ts

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DATA, ROOT } from './paths.ts';
+import type { Skill } from '../shared.ts';
+
+// Skills are Markdown instructions an author runs with "/" in the composer.
+// Papilot ships some in skills/; the data folder's skills/ adds the author's
+// own for every paper, and a paper's .papilot/skills/ its own. A later source
+// replaces an earlier skill with the same name. Each skill is <name>.md, or a
+// folder with a SKILL.md (the Agent Skills layout) whose other files the
+// agent may read. Front matter gives its name, description, composer hint
+// and order.
+export interface SkillFile extends Skill { body: string; folder?: string; order: number }
+const NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+
+export function parseSkill(text: string, id: string, source: Skill['source'], folder?: string): SkillFile | null {
+  text = text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+  const header = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text), fields: Record<string, string> = {};
+  for (const line of header?.[1].split('\n') || []) {
+    const field = /^([A-Za-z-]+):\s*(.*)$/.exec(line);
+    if (field) fields[field[1].toLowerCase()] = field[2].trim().replace(/^(['"])(.*)\1$/, '$2');
+  }
+  const body = text.slice(header ? header[0].length : 0).trim().slice(0, 20000);
+  if (!body) return null;
+  return { id, name: (fields.name || id).slice(0, 60), description: (fields.description || '').slice(0, 300), hint: (fields.hint || '').slice(0, 200), source, body, ...(folder ? { folder } : {}), order: fields.order && Number.isFinite(Number(fields.order)) ? Number(fields.order) : 1000 };
+}
+
+function read(dir: string, source: Skill['source']): SkillFile[] {
+  let entries: fs.Dirent[];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  const found: SkillFile[] = [];
+  for (const entry of entries) {
+    const id = entry.name.replace(/\.md$/i, '').toLowerCase();
+    if (!NAME.test(id)) continue;
+    try {
+      const skill = entry.isDirectory() ? parseSkill(fs.readFileSync(path.join(dir, entry.name, 'SKILL.md'), 'utf8'), id, source, path.join(dir, entry.name))
+        : entry.isFile() && /\.md$/i.test(entry.name) ? parseSkill(fs.readFileSync(path.join(dir, entry.name), 'utf8'), id, source) : null;
+      if (skill) found.push(skill);
+    } catch { /* A folder without a readable SKILL.md is not a skill. */ }
+  }
+  return found;
+}
+
+export function loadSkills(paper?: string, roots = { builtin: path.join(ROOT, 'skills'), user: path.join(DATA, 'skills') }): SkillFile[] {
+  const skills = new Map<string, SkillFile>();
+  const sources: [string, Skill['source']][] = [[roots.builtin, 'builtin'], [roots.user, 'user'], ...(paper ? [[path.join(paper, '.papilot', 'skills'), 'paper'] as [string, Skill['source']]] : [])];
+  for (const [dir, source] of sources) for (const skill of read(dir, source)) skills.set(skill.id, skill);
+  return [...skills.values()].sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
+}
+
+export function findSkill(paper: string, id: string) {
+  const skill = loadSkills(paper).find(item => item.id === id);
+  if (!skill) throw new Error(`The skill "${id}" is not available for this paper.`);
+  return skill;
+}
+
+export const listedSkill = ({ id, name, description, hint, source }: SkillFile): Skill => ({ id, name, description, hint, source });

package/src/server/workspace.ts

@@ -9,7 +9,9 @@ import { Codex, RpcResponseError } from './codex.ts';
 import { AGENT_NAMES, AntigravityAgent, ClaudeAgent, type AgentRuntime } from './agents.ts';
 import { reviewClient, taskRoute, confirmedReviewResponse, type ReviewClient } from './review.ts';
 import { VERSION } from './paths.ts';
-import type { Task, Run, TimelineItem, PendingRequest, RuntimeStatus, Snapshot, PendingReview, AgentModel, Usage, AgentId } from '../shared.ts';
+import { findSkill, type SkillFile } from './skills.ts';
+import { reviewInstructions, skillPrompt, summarizeFeedback } from '../conversation.ts';
+import type { Task, Run, TimelineItem, PendingRequest, RuntimeStatus, Snapshot, PendingReview, AgentModel, Usage, AgentId, MessageMeta, FeedbackSummary } from '../shared.ts';
 
 const execute = promisify(execFile);
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
@@ -122,25 +124,30 @@ export class Workspace extends EventEmitter {
     const project = { ...this.store.project(projectId), name };
     this.store.saveProject(project); return project;
   }
-  async createTask(input: { projectId: string; title: string; instructions: string; agent?: AgentId; model?: string; effort?: string; id: string }) {
+  // A task can start from a skill; its instructions are then the author's own words, possibly none.
+  async createTask(input: { projectId: string; title: string; instructions: string; skill?: string; agent?: AgentId; model?: string; effort?: string; id: string }) {
     if (!/^[\w-]{16,64}$/.test(input.id)) throw new Error('Invalid task ID.');
     if (this.store.taskDeleted(input.id)) throw new Error('This task was deleted. Create a new task instead.');
     const existing = this.store.tasks().find(t => t.id === input.id); if (existing) return existing;
     if (this.preparing.has(input.id)) throw new Error('This task is being created. Refresh in a moment.');
     this.preparing.add(input.id);
     try {
-      const project = this.store.project(input.projectId), client = await this.connectReview(project.path);
+      const project = this.store.project(input.projectId), skill = input.skill ? findSkill(project.path, input.skill) : undefined;
+      if (!skill && !input.instructions.trim()) throw new Error('Describe the revision, or choose a skill.');
+      const client = await this.connectReview(project.path);
       const name = 'p-' + input.id.toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 48);
       const info = await client.post('/api/tasks', { name, title: input.title });
-      const task: Task = { id: input.id, projectId: project.id, name, title: input.title, instructions: input.instructions,
+      const task: Task = { id: input.id, projectId: project.id, name, title: input.title, instructions: skill ? skillPrompt(skill, input.instructions) : input.instructions,
         worktree: info.worktree, threadId: null, turnId: null, agent: input.agent || 'codex', model: input.model || null, effort: input.effort || null, status: 'idle',
         createdAt: Date.now(), updatedAt: Date.now(), feedbackCursor: 0, error: null, review: null };
       this.store.saveTask(task);
-      await this.enqueue(task.id, input.instructions, 'initial-' + task.id, false);
+      await this.enqueue(task.id, input.instructions, 'initial-' + task.id, false, { skill });
       return this.store.task(task.id);
     } finally { this.preparing.delete(input.id); }
   }
-  async enqueue(taskId: string, text: string, requestKey: string, includeFeedback = true) {
+  // The author's message, a skill run with or without one, or the review
+  // feedback alone. The chat keeps what the author did; the agent gets the prompt.
+  async enqueue(taskId: string, text: string, requestKey: string, includeFeedback = true, options: { skill?: SkillFile; feedback?: boolean } = {}) {
     const task = this.store.task(taskId);
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
     const existing = this.store.runByKey(requestKey);
@@ -148,15 +155,18 @@ export class Workspace extends EventEmitter {
     if (task.status === 'uncertain') throw new Error('Check the task status before sending more instructions.');
     const pauseVersion = task.pauseVersion || 0;
     if (this.store.runs().some(r => r.taskId === taskId && r.status === 'queued')) throw new Error('This task already has queued instructions. Wait or pause it first.');
-    let prompt = text.trim(), cursor = task.feedbackCursor;
+    let prompt = options.feedback ? reviewInstructions : options.skill ? skillPrompt(options.skill, text) : text.trim(), cursor = task.feedbackCursor;
+    let summary: FeedbackSummary | undefined;
     if (includeFeedback) {
       const client = await this.connectReview(this.store.project(task.projectId).path);
       const feedback = await client.get(`${taskRoute(task.name)}/feedback?after=${task.feedbackCursor}`);
-      cursor = feedback.cursor;
+      cursor = feedback.cursor; summary = summarizeFeedback(feedback);
+      if (options.feedback && !summary) throw new Error('There is no new review feedback to send.');
       if (feedback.feedback?.length || feedback.build_error) prompt += '\n\nPapilot review feedback (bound to the specified review round and source changes):\n' + JSON.stringify(feedback, null, 2);
       if (task.error) prompt += '\n\nLatest task/review error:\n' + task.error + '\nThe latest accepted manuscript is at ' + this.store.project(task.projectId).path + '. You may read it to understand accepted changes, but must only edit your isolated task worktree. Prepare a revised proposal for another review; never write to or accept changes in the manuscript checkout.';
     }
     const run: Run = { id: randomUUID(), taskId, requestKey, prompt, feedbackCursor: cursor, status: 'queued', createdAt: Date.now(), finishedAt: null };
+    const meta: MessageMeta = { ...(options.skill ? { skill: { id: options.skill.id, name: options.skill.name } } : {}), ...(summary ? { feedback: summary } : {}), ...(options.feedback ? { sendsFeedback: true } : {}) };
     const saved = this.store.transaction(() => {
       // Feedback loading yields to other requests. Recheck identity, queue, and
       // task status together before committing; none of the earlier reads own a lock.
@@ -172,7 +182,7 @@ export class Workspace extends EventEmitter {
       if (current.status === 'uncertain') throw new Error('Check the task status before sending more instructions.');
       this.store.saveRun(run);
       if (!BUSY.has(current.status)) this.store.updateTask(taskId, { status: 'queued', error: null });
-      this.store.saveItem({ id: run.id, taskId, type: 'user', text: text.trim(), createdAt: run.createdAt });
+      this.store.saveItem({ id: run.id, taskId, type: 'user', text: options.feedback ? '' : text.trim(), createdAt: run.createdAt, ...(Object.keys(meta).length ? { meta } : {}) });
       return run;
     });
     this.schedule();
@@ -200,7 +210,7 @@ export class Workspace extends EventEmitter {
 Your task is already created. Your editable working directory is ${task.worktree}.
 Original task: ${task.instructions}
 Only edit this isolated task worktree. Never edit the manuscript checkout, other task worktrees, or Papilot's own source/state. Never commit, push, stash, or accept/reject/undo review decisions.
-Papilot owns the LaTeX review lifecycle: it compiles and publishes automatically AFTER your turn finishes, and delivers review feedback in a new turn. Do not create another review task, invoke publish, or wait on feedback --wait. This application workflow replaces the standalone latex-review skill's publish-and-wait loop. End your turn after completing the requested edits, with a concise summary.
+Papilot owns the LaTeX review lifecycle: it compiles and publishes automatically AFTER your turn finishes, and delivers review feedback in a new turn. Do not create another review task, invoke publish, or wait on feedback --wait. This application workflow replaces the standalone latex-review skill's publish-and-wait loop. End your turn after completing the requested edits, with a concise summary for the author of what you changed and why; do not describe Papilot's review workflow.
 Preserve meaning and mathematical correctness. Read relevant project instructions. Treat reviewer comments as instructions tied to their round, file and changes. Rejected edits must not be reintroduced unless explicitly requested. If there is a conflict with accepted text, explain it and propose a revision for a new review round; never overwrite the accepted manuscript.
 ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to you here and any attempt is refused, which ends your turn: read, search and edit files in the task worktree with your file tools only.' : 'You may run tools in the task worktree to inspect and validate your changes.'} If a decision requires the user, ask through the available user-input tool or explain it in your final response. Use English for your progress updates, questions, and final summaries unless the user explicitly requests another language. Preserve the manuscript language unless asked to translate it.`;
   }
@@ -460,7 +470,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
         if (this.closing) return;
         const current = await client.get(`/api/jobs/${job.job}`);
         const summary = await client.get(taskRoute(task.name));
-        this.store.updateTask(taskId, { review: { state: summary.state, round: summary.round, counts: summary.counts, job: current, unsent: this.store.task(taskId).review?.unsent } });
+        this.store.updateTask(taskId, { review: { ...this.store.task(taskId).review, state: summary.state, round: summary.round, counts: summary.counts, job: current } });
         if (current.status === 'done' || current.status === 'completed' || current.status === 'succeeded') break;
         if (current.status === 'failed') throw new Error([current.error, ...(current.details || [])].filter(Boolean).join('\n') || 'PDF build failed.');
         await delay(1500);
@@ -473,19 +483,22 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     try {
       const task = this.store.task(taskId);
       if (task.status === 'deleting') return;
-      const client = await this.connectReview(this.store.project(task.projectId).path);
+      const project = this.store.project(task.projectId), client = await this.connectReview(project.path);
       const summary = await client.get(taskRoute(task.name));
-      const unsent = await this.unsentComments(client, this.store.task(taskId));
+      const { unsent, comments } = await this.unsentReviewFeedback(client, this.store.task(taskId));
+      const files = await acceptedFiles(project.path, task.name);
       const current = this.store.task(taskId);
-      if (current.status !== 'deleting') this.store.updateTask(taskId, { review: { state: summary.state, round: summary.round, counts: summary.counts, job: current.review?.job, unsent } });
+      if (current.status !== 'deleting') this.store.updateTask(taskId, { review: { state: summary.state, round: summary.round, counts: summary.counts, job: current.review?.job, unsent, comments, files } });
     } catch { /* The task remains visible even if its project is temporarily unavailable. */ }
   }
-  // Review comments Codex has not received yet. A queued or in-flight message
-  // already carries the feedback up to its own cursor.
-  private async unsentComments(client: ReviewClient, task: Task) {
+  // Review decisions, comments and undo updates the agent has not received yet.
+  // The engine excludes decisions undone before delivery. A queued or in-flight message
+  // already carries the feedback up to its own cursor. Comments and notes ask for a revision.
+  private async unsentReviewFeedback(client: ReviewClient, task: Task) {
     const after = Math.max(task.feedbackCursor, ...this.store.runs().filter(r => r.taskId === task.id && ['queued', 'running', 'uncertain'].includes(r.status)).map(r => r.feedbackCursor || 0));
     const feedback = await client.get<{ feedback?: { kind?: string }[] }>(`${taskRoute(task.name)}/feedback?after=${after}`);
-    return (feedback.feedback || []).filter(item => item.kind === 'comment').length;
+    const items = feedback.feedback || [];
+    return { unsent: items.length, comments: items.filter(item => item.kind === 'comment' || item.kind === 'note').length };
   }
   renameTask(taskId: string, title: string) {
     if (this.store.task(taskId).status === 'deleting') throw new Error('This task is being deleted.');
@@ -528,3 +541,13 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   }
   close() { this.closing = true; for (const timer of this.usageTimers.values()) clearTimeout(timer); this.flush(); for (const id of AGENTS) this.agents[id].close(); }
 }
+
+// The review engine records each task's accepted text as a commit beside the
+// one it started from; their difference is what the task put in the
+// manuscript. A rename counts as both of its paths.
+export async function acceptedFiles(root: string, name: string) {
+  try {
+    const { stdout } = await execute('git', ['-C', root, 'diff', '--name-only', '--no-renames', '-z', `refs/latex-review/${name}/base`, `refs/latex-review/${name}/accepted`, '--']);
+    return stdout.split('\0').filter(Boolean);
+  } catch { return []; }
+}

package/src/shared.ts

@@ -1,6 +1,9 @@
 export type TaskStatus = 'idle' | 'queued' | 'running' | 'waiting_input' | 'building' | 'reviewing' | 'interrupted' | 'failed' | 'uncertain' | 'deleting';
 export interface Project { id: string; name: string; path: string; createdAt: number }
-export interface ReviewSummary { state: string; round: number | null; counts: Record<string, number>; unsent?: number; next?: string; job?: { phase: string; status: string; error?: string; details?: string[] } | null }
+// unsent counts review updates the agent has not received; comments are the
+// ones that ask for a revision. files are the manuscript files this task's
+// accepted changes touched, relative to the repository root.
+export interface ReviewSummary { state: string; round: number | null; counts: Record<string, number>; unsent?: number; comments?: number; files?: string[]; next?: string; job?: { phase: string; status: string; error?: string; details?: string[] } | null }
 export interface PendingReview { route: string; body: Record<string, unknown>; previousStatus: TaskStatus }
 export interface Task {
   id: string; projectId: string; name: string; title: string; instructions: string;
@@ -11,7 +14,12 @@ export interface Task {
   pendingReview?: PendingReview | null;
 }
 export interface Run { id: string; taskId: string; requestKey: string; prompt: string; feedbackCursor?: number; status: 'queued' | 'running' | 'completed' | 'failed' | 'interrupted' | 'uncertain'; createdAt: number; finishedAt: number | null }
-export interface TimelineItem { id: string; taskId: string; type: string; text: string; detail?: string; status?: string; createdAt: number }
+export interface TimelineItem { id: string; taskId: string; type: string; text: string; detail?: string; status?: string; createdAt: number; meta?: MessageMeta }
+// A user message can run a skill or carry review feedback; the chat shows
+// those as what they are rather than as the prompt the agent receives.
+export interface MessageMeta { skill?: { id: string; name: string }; feedback?: FeedbackSummary; sendsFeedback?: boolean }
+export interface FeedbackSummary { round: number | null; accepted: number; rejected: number; undone: number; comments: { where: string; text: string }[]; buildError?: boolean }
+export interface Skill { id: string; name: string; description: string; hint: string; source: 'builtin' | 'user' | 'paper' }
 export interface PendingRequest { id: string; taskId: string; method: string; params: Record<string, any>; createdAt: number }
 export type AgentId = 'codex' | 'claude' | 'antigravity';
 export interface AgentModel { id: string; name: string; isDefault: boolean; efforts: string[]; defaultEffort: string | null }