papilot 0.0.0-stage → 0.1.0

package/examples/papilot-paper/sections/08-notes.tex

@@ -0,0 +1,104 @@
+\section{Notes on the PDF}
+\label{sec:notes}
+
+An author can also ask for changes directly on the PDF: select text, or mark a
+region around a figure or an equation, and write a note. All pending notes go
+to the agent as one task. For that task to be useful, each note must name the
+source it refers to.
+
+\subsection{From a mark to source lines}
+
+A note is a set of rectangles $\{r_1, \dots, r_q\}$ in the normalised
+coordinates of \cref{eq:normalised} on page $P$, together with a comment. For
+every printed line the selection touches, Papilot asks SyncTeX for the source
+position of the first and the last marked character~\cite{laurens2008}:
+\begin{equation}
+  \mathcal{S}(P, x, y) = (\text{file}, \text{line}),
+  \qquad
+  L = \{\, \mathcal{S}(P, c) : c \in C_{\text{first}} \cup C_{\text{last}} \,\},
+  \qquad
+  [\ell_{-}, \ell_{+}] = [\min L, \max L].
+  \label{eq:synctex-range}
+\end{equation}
+
+SyncTeX records boxes and glue rather than characters. The space before a word
+that begins a printed line comes from the line break of the \emph{previous}
+source line, so such a word is credited to that line. Papilot therefore
+\emph{settles} each end of the selection by matching its printed context
+against the source near SyncTeX's answer.
+
+\subsection{Settling a selection}
+
+Let $\letters(\cdot)$ map text to its lowercase letters and digits, after
+Unicode compatibility normalisation, with \TeX{} control sequences and comments
+removed from the source. For a source window $[\ell_{-} - 4, \ell_{+} + 4]$ we
+form the string $S = \letters(\text{lines})$ and remember for each position the
+line it came from, $\pi : \{1, \dots, \abs{S}\} \to \N$. The distance of a
+line from SyncTeX's range is
+\begin{equation}
+  \dist(\ell) = \max\bigl(0,\ \ell_{-} - \ell,\ \ell - \ell_{+}\bigr).
+  \label{eq:line-distance}
+\end{equation}
+
+\begin{algorithm}[t]
+\caption{Settling one end of a selection}
+\label{alg:settle}
+\begin{algorithmic}[1]
+\Require printed line $p$, index $\alpha$ of the marked letter in $\letters(p)$, source string $S$ with line map $\pi$
+\For{$\rho \in (\infty, 24, 10)$} \Comment{whole line first, then shorter context}
+  \State $o_0 \gets \max(0, \alpha - \rho)$
+  \State $q \gets \letters(p)_{[o_0,\ \alpha + \rho]}$
+  \State $O \gets \{ o : S_{[o,\, o + \abs{q})} = q \}$
+  \If{$O \neq \emptyset$}
+    \State $o^{\star} \gets \argmin_{o \in O} \dist\bigl(\pi(o + \alpha - o_0)\bigr)$
+    \State \Return $\pi\bigl(o^{\star} + \alpha - o_0\bigr)$
+  \EndIf
+\EndFor
+\State \Return SyncTeX's line \Comment{formulas and other unmatched text}
+\end{algorithmic}
+\end{algorithm}
+
+\Cref{alg:settle} runs once for the first and once for the last marked
+character. If the settled range is empty or inverted, Papilot keeps SyncTeX's
+range. Because the comparison uses letters only, subscripts, macros and
+hyphenation do not prevent a match; formulas, whose printed form shares no
+letters with their source, fall back to SyncTeX by design.
+
+\subsection{When is a match unique?}
+
+\Cref{alg:settle} picks the occurrence nearest to SyncTeX's answer, so a
+spurious occurrence matters only if it is closer than the true one. Model the
+letters of the source as a stationary source with entropy $\mathcal{H}$ bits per letter.
+The expected number of chance occurrences of a context of $\abs{q}$ letters in
+a window of $\abs{S}$ letters is about
+\begin{equation}
+  \E[\text{spurious}] \approx \abs{S} \cdot 2^{-\mathcal{H} \abs{q}} .
+  \label{eq:spurious}
+\end{equation}
+Estimates of the entropy of English range from about one to four bits per
+letter depending on how much context is used~\cite{shannon1951}. Even with the
+pessimistic $\mathcal{H} = 1$, a context of $\abs{q} = 21$ letters (the shortest one
+\cref{alg:settle} tries) in a window of $\abs{S} = 2000$ letters gives
+$\E[\text{spurious}] \approx 2000 \cdot 2^{-21} \approx 10^{-3}$. Spurious
+matches come instead from genuine repetition, such as a phrase used twice in
+nearby paragraphs, which is exactly the case the distance
+\cref{eq:line-distance} resolves.
+
+\subsection{Selecting whole words}
+
+Let a drag select characters $[s, t)$ of the per-word text layer of
+\cref{thm:per-word}. Papilot widens the selection to whole words, but only at
+a boundary that cuts through a word:
+\begin{equation}
+  s' = \begin{cases}
+    \max\{ i \le s : \text{$i = 0$ or $c_{i-1}$ is not a letter} \}, &
+      c_s \text{ is a letter},\\
+    s, & \text{otherwise},
+  \end{cases}
+  \label{eq:whole-words}
+\end{equation}
+and symmetrically for $t$. A drag that ends at the start of the next word, as
+browsers often report, therefore keeps exactly the words it covers. The note
+stores the widened quote, one rectangle per printed line, and the source lines
+of \cref{alg:settle} together with an excerpt of their \LaTeX{}, so that the
+agent receives formulas as source rather than as extracted text.

package/examples/papilot-paper/sections/09-agents.tex

@@ -0,0 +1,106 @@
+\section{Agents and scheduling}
+\label{sec:agents}
+
+\subsection{One protocol for three agents}
+
+Every agent is driven through the same small protocol: a thread is started or
+resumed, a turn is started with the author's text, the agent streams items
+(messages, commands, file changes, questions), and the turn completes, is
+interrupted, or fails. Formally a task moves through the states of
+\cref{fig:states}.
+
+\begin{figure}[t]
+\centering
+\begin{tikzpicture}[
+  >={Stealth[length=2.2mm]}, node distance=2.1cm and 2.6cm,
+  every state/.style={draw=blue!50!black, thick, fill=blue!4, rounded corners=3pt,
+    rectangle, minimum width=1.9cm, minimum height=0.8cm, font=\small\sffamily},
+  every edge/.style={draw, ->, thick, gray!70!black},
+  lbl/.style={font=\scriptsize\sffamily, fill=white, inner sep=1pt}]
+  \node[state, initial, initial text={}] (idle) {idle};
+  \node[state, right=of idle] (queued) {queued};
+  \node[state, right=of queued] (running) {running};
+  \node[state, below=1.6cm of running] (building) {building};
+  \node[state, left=of building] (reviewing) {reviewing};
+  \node[state, above=1.5cm of running] (waiting) {waiting input};
+  \node[state, above=1.5cm of idle] (paused) {paused};
+  \path (idle) edge node[lbl, above] {instructions} (queued)
+        (queued) edge node[lbl, above] {slot free} (running)
+        (running) edge[bend right=28] node[lbl, right] {approval} (waiting)
+        (waiting) edge[bend right=28] node[lbl, left] {answer} (running)
+        (running) edge node[lbl, right] {turn done} (building)
+        (building) edge node[lbl, below] {published} (reviewing)
+        (reviewing) edge node[lbl, left] {feedback} (queued)
+        (running) edge[out=150, in=0, looseness=0.9] node[lbl, above, pos=0.45] {pause} (paused)
+        (paused) edge node[lbl, left] {resume} (idle);
+\end{tikzpicture}
+\caption{Task states. A turn that fails or whose outcome is uncertain leaves the
+task in a recoverable state with a \emph{Check status} action (not shown).}
+\label{fig:states}
+\end{figure}
+
+Codex speaks this protocol natively. Claude runs through the Claude Agent SDK,
+and Antigravity runs the \texttt{agy} command line once per turn; both are
+translated by small adapters into the same requests and notifications. Each
+agent uses its own login on the host, and Papilot never reads, stores or
+forwards a credential. An agent that cannot ask for permission, such as a
+headless command line, is told in advance which tools it may not use.
+
+\subsection{Effort and cost}
+
+A reasoning effort $\epsilon$ from the ordered set
+\begin{equation}
+  \mathcal{E} = \{\textsf{low} < \textsf{medium} < \textsf{high} <
+  \textsf{xhigh} < \textsf{max}\}
+\end{equation}
+is chosen per task and remembered per agent. If a turn at effort $\epsilon$
+consumes on average $\kappa(\epsilon)$ tokens and produces an accepted change
+with probability $q(\epsilon)$, the number of turns until acceptance is
+geometric and the expected cost of an accepted change is
+\begin{equation}
+  \operatorname{cost}(\epsilon) = \frac{\kappa(\epsilon)}{q(\epsilon)}
+  \cdot \operatorname{price}, \qquad
+  \epsilon^{\star} = \argmin_{\epsilon \in \mathcal{E}}
+    \operatorname{cost}(\epsilon).
+  \label{eq:effort-cost}
+\end{equation}
+A lower effort is cheaper only if
+$\kappa(\epsilon) / \kappa(\epsilon') < q(\epsilon) / q(\epsilon')$: a failed
+turn must be paid for again, and so must the author's review of it.
+
+\subsection{Queueing}
+
+Tasks arrive at rate $\nu$ and occupy a slot for a mean time $1/\omega$. With
+$c$ slots, exponential times and offered load $A = \nu/\omega < c$, Papilot is
+an $M/M/c$ queue~\cite{kleinrock1975}. The probability that a new task waits is
+given by the Erlang~C formula~\cite{erlang1917}:
+\begin{equation}
+  C(c, A) =
+  \frac{\dfrac{A^{c}}{c!}\,\dfrac{c}{c - A}}
+       {\displaystyle\sum_{k=0}^{c-1} \frac{A^{k}}{k!}
+        + \frac{A^{c}}{c!}\,\frac{c}{c - A}},
+  \qquad
+  \E[\text{wait}] = \frac{C(c, A)}{c\,\omega - \nu} .
+  \label{eq:erlang}
+\end{equation}
+For $c = 2$ this simplifies to $C(2, A) = A^2 / (2 + A)$. An author who starts
+a task every ten minutes, each taking six minutes, has $A = 0.6$ and waits
+with probability about $0.14$, for $0.14 / (2/6 - 1/10) \approx 0.6$ minutes on
+average. By Little's law~\cite{little1961}, the mean number of tasks in the
+system is
+\begin{equation}
+  \bar{N} = \nu \Bigl( \E[\text{wait}] + \frac{1}{\omega} \Bigr) .
+  \label{eq:little}
+\end{equation}
+
+\subsection{Approvals}
+
+A turn that asks for approval stops until the author answers. If approvals
+arrive at rate $\zeta$ during a turn of working time $T_w$ and the author
+answers after a mean delay $\Theta$, the expected wall-clock time of the turn is
+\begin{equation}
+  \E[T] = T_w \bigl(1 + \zeta \Theta\bigr),
+  \label{eq:approvals}
+\end{equation}
+which is why Papilot lets agents edit and run sandboxed commands in the task's
+worktree without asking, and asks only for what leaves it.

package/examples/papilot-paper/sections/10-usage.tex

@@ -0,0 +1,56 @@
+\section{Usage windows}
+\label{sec:usage}
+
+\subsection{Utilisation}
+
+Agent subscriptions meter usage over rolling windows, typically a five-hour
+window and a weekly one. If $r(\tau)$ is the rate at which a plan's allowance
+is consumed, the utilisation of a window of length $w$ at time $t$ is
+\begin{equation}
+  u_w(t) = \frac{1}{B_w} \int_{t-w}^{t} r(\tau)\, d\tau \in [0, 1],
+  \label{eq:utilisation}
+\end{equation}
+where $B_w$ is the window's budget. Papilot shows $u_w$ for each window the
+agent reports, coloured by thresholds
+\begin{equation}
+  \operatorname{colour}(u) =
+  \begin{cases}
+    \text{blue}, & u < 0.75,\\
+    \text{amber}, & 0.75 \le u < 0.9,\\
+    \text{red}, & u \ge 0.9 \ \text{or the limit is reached},
+  \end{cases}
+\end{equation}
+together with the reset time: as a countdown when it is less than a day away,
+and as a day and time otherwise.
+
+\subsection{Will the limit be reached?}
+
+At a constant rate $\bar r$, the time left before the limit is
+\begin{equation}
+  t_{\text{left}} = \frac{\bigl(1 - u_w(t)\bigr) B_w}{\bar r} ;
+\end{equation}
+with the weekly window at $u = 0.83$ and an even pace over the week,
+$\bar r = B_w / 7$\,days and about $1.2$ days of work remain.
+
+Usage is lumpy, however: it arrives in turns. Model turns as a Poisson process
+of rate $\lambda$ with independent costs $J$ of mean $\mu_J$ and variance
+$s_J^2$. The usage $S(t)$ over the next $t$ is compound Poisson, with
+\begin{equation}
+  \E[S(t)] = \lambda t \mu_J, \qquad
+  \Var\bigl(S(t)\bigr) = \lambda t \bigl(\mu_J^2 + s_J^2\bigr)
+  \label{eq:compound}
+\end{equation}
+by Wald's identity and the law of total variance~\cite{feller1968}. With $t_r$ the time until the window
+resets, the normal approximation gives the probability of reaching the limit
+before the reset:
+\begin{equation}
+  \Prob\bigl(S(t_r) > (1 - u) B_w\bigr) \approx
+  1 - \Phi\!\left(
+    \frac{(1 - u) B_w - \lambda t_r \mu_J}
+         {\sqrt{\lambda t_r (\mu_J^2 + s_J^2)}}
+  \right),
+  \label{eq:limit-probability}
+\end{equation}
+where $\Phi$ is the standard normal distribution function. Large, rare turns
+(high $s_J$) make the limit more likely than the mean alone suggests, which is
+one more reason to prefer a lower effort for routine edits.

package/examples/papilot-paper/sections/11-git.tex

@@ -0,0 +1,62 @@
+\section{Closing the loop with Git}
+\label{sec:git}
+
+Accepted changes land in the working tree without a commit, so that the author
+decides what history to write. The Git panel shows the branch and how it
+compares with its upstream, the last commit, and the uncommitted changes with
+their diffs; from it the author commits chosen files, fetches, pulls and
+pushes.
+
+\subsection{Committing chosen files}
+
+Write a tree as a map from paths to contents and, for a set of paths $P$, let
+$X|_P$ be the restriction of $X$ to $P$ and $\overline{P}$ the complement. Let
+$\mathrm{HEAD}$ have tree $H$, let $I$ be the index and $W$ the working tree,
+and let $P$ be the set of paths the author ticks.
+
+\begin{proposition}[Partial commits]
+\label{prop:partial}
+Committing $P$ produces the tree and leaves the index as
+\begin{equation}
+  T_{c} = H|_{\overline{P}} \cup W|_{P},
+  \qquad
+  I' = I|_{\overline{P}} \cup W|_{P},
+  \label{eq:partial}
+\end{equation}
+that is, exactly the chosen files as they are on disk are committed, while
+anything staged for other paths stays staged and out of the commit. A rename
+from $\pi$ to $\pi'$ contributes both $\pi$ and $\pi'$ to $P$.
+\end{proposition}
+
+The proof, which follows the semantics of \texttt{git add} followed by
+\texttt{git commit --only}, is in \cref{app:proofs}. Paths are passed to Git
+literally, so that a file name cannot act as a pattern, and new \LaTeX{} build
+output (\texttt{.aux}, \texttt{.log} and similar files) starts unticked.
+
+\subsection{Synchronising with the remote}
+
+Let $\anc(X)$ be the set of commits reachable from $X$, including $X$. With
+local head $L$ and upstream $U$, the branch is ahead and behind by
+\begin{equation}
+  \operatorname{ahead} = \abs{\anc(L) \setminus \anc(U)}, \qquad
+  \operatorname{behind} = \abs{\anc(U) \setminus \anc(L)},
+  \label{eq:ahead-behind}
+\end{equation}
+the two numbers shown beside the branch name. Pull is a fast-forward only. It
+succeeds exactly when
+\begin{equation}
+  \anc(L) \subseteq \anc(U)
+  \iff \operatorname{merge-base}(L, U) = L
+  \iff \operatorname{ahead} = 0,
+  \label{eq:fast-forward}
+\end{equation}
+in which case $L \leftarrow U$; otherwise Papilot reports the divergence and
+never merges or rebases on the author's behalf. Push is the mirror image and
+succeeds when $\operatorname{behind} = 0$. A branch without an upstream is
+published with its first push.
+
+\begin{remark}
+Fetch, pull and push use the host's own Git credentials with prompts disabled
+and a time limit, so that a missing credential produces Git's own error message
+instead of a request that hangs.
+\end{remark}

package/examples/papilot-paper/sections/12-security.tex

@@ -0,0 +1,41 @@
+\section{Security}
+\label{sec:security}
+
+Papilot runs on the author's own computer and can be reached from other
+devices over a private network. Its threat model is a web page in another tab
+that tries to act on the author's behalf, and a device on the network that is
+not the author's.
+
+\subsection{Requests}
+
+Every state-changing request must carry a token $\chi$ of $256$ random bits,
+issued with the page and compared in constant time, which defends against
+cross-site request forgery~\cite{barth2008}. A remote request must also come
+from the configured origin and, over the private network, from the configured
+owner. Writing $\rho$ for a request,
+\begin{equation}
+  \operatorname{allow}(\rho) =
+  \bigl(\operatorname{safe}(\rho) \lor \operatorname{token}(\rho) = \chi\bigr)
+  \land \operatorname{origin}(\rho) \in \mathcal{O}
+  \land \operatorname{owner}(\rho) = o ,
+  \label{eq:allow}
+\end{equation}
+where $\operatorname{safe}(\rho)$ holds for requests that only read. A guess
+succeeds with probability $2^{-256}$, and a constant-time comparison leaks no
+prefix of $\chi$ through timing.
+
+\subsection{Agents}
+
+Agents run with the author's own logins but within limits Papilot sets:
+\begin{itemize}
+  \item each task's agent works in its own worktree $w_i$ and is told never to
+    edit the manuscript checkout $w_0$, other worktrees, or Papilot itself;
+  \item commands run in the agent's sandbox, and anything that leaves it is
+    either brought to the author for approval or, for an agent that cannot
+    ask, declined in advance;
+  \item only the author accepts changes into $w_0$, through the review of
+    \cref{sec:model}.
+\end{itemize}
+The last point is the one that matters most: even an agent that ignored its
+instructions could not change the manuscript without a decision the author
+made while looking at the typeset result.

package/examples/papilot-paper/sections/13-evaluation.tex

@@ -0,0 +1,106 @@
+\section{A model-based evaluation}
+\label{sec:evaluation}
+
+This section evaluates the models of the previous sections numerically. Every
+number below is computed from a formula in this paper; none is measured. The
+purpose is to show what the formulas imply for realistic parameters, not to
+report an empirical study.
+
+\subsection{Rounds per task}
+
+\Cref{tab:rounds} evaluates \cref{prop:rounds} and \cref{cor:rounds} for a
+range of acceptance probabilities and numbers of changes. Two patterns stand
+out. The expected number of rounds grows only logarithmically with the number
+of changes, as the harmonic-number approximation predicts. And the
+95\,\% bound $r_{0.05}$ is at most two and a half times the mean in every case
+shown, so that at $p = 0.7$ a task with five changes that is still open after
+four rounds is among the slowest five per cent, and worth rewriting rather than
+reviewing again.
+
+\begin{table}[t]
+\centering
+\caption{Expected rounds $\E[R_{\max}]$ from \cref{eq:rounds}, and in
+parentheses the rounds $r_{0.05}$ within which a task ends with probability
+at least $0.95$ from \cref{eq:rounds-confidence}.}
+\label{tab:rounds}
+\begin{tabular}{@{}lccccc@{}}
+\toprule
+& \multicolumn{5}{c}{changes per task $m$} \\
+\cmidrule(l){2-6}
+acceptance $p$ & 1 & 2 & 5 & 10 & 20 \\
+\midrule
+$0.5$ & 2.00 (5) & 2.67 (6) & 3.79 (7) & 4.73 (8) & 5.69 (9) \\
+$0.7$ & 1.43 (3) & 1.76 (4) & 2.39 (4) & 2.93 (5) & 3.49 (5) \\
+$0.9$ & 1.11 (2) & 1.21 (2) & 1.46 (2) & 1.76 (3) & 2.08 (3) \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+\subsection{Conflicts}
+
+\Cref{tab:conflicts} evaluates \cref{eq:conflict} for two concurrent tasks with
+edits of $\ell = 200$ characters. A $10$-page paper has about
+$3 \times 10^{4}$ characters of source, a $40$-page paper about
+$1.2 \times 10^{5}$ and a thesis about $4.8 \times 10^{5}$. By
+\cref{cor:clustered}, confining both tasks to a quarter of a document moves a
+row up one line.
+
+\begin{table}[t]
+\centering
+\caption{Probability that two concurrent tasks with $k$ edits each conflict,
+from \cref{eq:conflict} with $\ell = 200$.}
+\label{tab:conflicts}
+\begin{tabular}{@{}lccc@{}}
+\toprule
+& \multicolumn{3}{c}{edits per task $k$} \\
+\cmidrule(l){2-4}
+source length $n$ & 5 & 10 & 20 \\
+\midrule
+$3.0 \times 10^{4}$ (short paper) & 0.284 & 0.737 & 0.995 \\
+$1.2 \times 10^{5}$ (long paper) & 0.080 & 0.284 & 0.737 \\
+$4.8 \times 10^{5}$ (thesis) & 0.021 & 0.080 & 0.284 \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+\subsection{Waiting for a slot}
+
+\Cref{fig:erlang} plots the waiting probability \cref{eq:erlang} against the
+offered load for one, two and three slots. At the load $A = 0.6$ of the example
+in \cref{sec:agents}, a second slot lowers the probability of waiting from
+$0.6$ to $0.14$, and a third would lower it to $0.025$. Two slots are a good
+compromise between waiting and the conflicts of \cref{tab:conflicts}, which
+grow with the number of tasks that run at once.
+
+\begin{figure}[t]
+\centering
+\begin{tikzpicture}
+\begin{axis}[
+  width=0.92\linewidth, height=5.4cm,
+  xlabel={offered load $A = \nu/\omega$}, ylabel={$C(c, A)$},
+  xmin=0, xmax=1.5, ymin=0, ymax=1,
+  legend style={at={(0.02,0.97)}, anchor=north west, draw=none, fill=white, font=\small},
+  grid=major, grid style={gray!20}, tick label style={font=\small}, label style={font=\small}]
+  \addplot[gray!70!black, thick, dashed, domain=0:0.999, samples=60] {x};
+  \addlegendentry{$c = 1$}
+  \addplot[blue!60!black, thick, domain=0:1.5, samples=60] {x^2/(2+x)};
+  \addlegendentry{$c = 2$}
+  \addplot[orange!80!black, thick, domain=0:1.5, samples=60]
+    {(x^3/6*3/(3-x))/(1+x+x^2/2+x^3/6*3/(3-x))};
+  \addlegendentry{$c = 3$}
+  \addplot[only marks, mark=*, mark size=1.6pt, blue!60!black] coordinates {(0.6,0.138)};
+\end{axis}
+\end{tikzpicture}
+\caption{Probability that a new task waits for a slot, from the Erlang~C
+formula \cref{eq:erlang}. The dot marks the example of \cref{sec:agents}.}
+\label{fig:erlang}
+\end{figure}
+
+\subsection{Selection error}
+
+For the text layer, \cref{fig:drift} already compares the two layouts. In
+numbers: with $v = (0.4\,\mathrm{pt})^2$ per glyph, a line of $80$ glyphs has a
+mid-line standard deviation of $0.4\sqrt{80/4} \approx 1.8$\,pt from
+\cref{eq:bridge} alone, plus the bias of \cref{eq:bias}, which reaches several
+points; per-word runs of seven glyphs bound it by $0.4\sqrt{7/4} \approx
+0.53$\,pt, well under the width of one letter.

package/examples/papilot-paper/sections/14-related.tex

@@ -0,0 +1,38 @@
+\section{Related work}
+\label{sec:related}
+
+\paragraph{Differences between documents.}
+Line-based differences go back to Hunt and McIlroy~\cite{hunt1976} and Myers's
+$O(ND)$ algorithm~\cite{myers1986}, which Git uses by default.
+\texttt{latexdiff}~\cite{latexdiff} marks up the differences between two
+\LaTeX{} sources so that they can be typeset together. Papilot instead
+typesets each version separately and shows the corresponding strips of the
+two PDFs one above the other, which keeps the typeset result of each version
+exact at the cost of a second build.
+
+\paragraph{Concurrent editing.}
+Operational transformation~\cite{ellis1989} and conflict-free replicated data
+types~\cite{shapiro2011} let several writers edit a shared document and converge
+without coordination. Papilot's setting is different: proposals are not applied
+until an author accepts them, so convergence is a property of accepted edits
+only, and \cref{lem:tp1} needs to hold only for compatible pairs. Incompatible
+pairs are surfaced to the author rather than transformed.
+
+\paragraph{Line breaking and text layers.}
+The Knuth--Plass algorithm~\cite{knuth1981} is the reason \LaTeX{} spaces vary
+from line to line, and with it the drift analysed in \cref{sec:geometry}. PDF
+viewers such as PDF.js~\cite{pdfjs} place an invisible text layer over the
+rendered page; Papilot uses PDF.js for rendering, search and links, and
+replaces only the placement of its text with the per-word runs of
+\cref{thm:per-word}.
+
+\paragraph{Source synchronisation.}
+SyncTeX~\cite{laurens2008} maps between typeset positions and source lines and
+underlies forward and inverse search in most \TeX{} editors. Papilot uses its
+reverse queries and corrects their line-boundary error with
+\cref{alg:settle}.
+
+\paragraph{Queueing.}
+The waiting-time results of \cref{sec:agents} are classical; we use Erlang's
+formula~\cite{erlang1917}, Little's law~\cite{little1961} and the treatment of
+$M/M/c$ queues in Kleinrock~\cite{kleinrock1975}.

package/examples/papilot-paper/sections/15-conclusion.tex

@@ -0,0 +1,27 @@
+\section{Discussion and conclusion}
+\label{sec:conclusion}
+
+\subsection{Limitations}
+
+Three limitations are worth stating. First, \cref{prop:conflict} assumes
+uniformly placed edits; real revisions cluster around the parts of a paper an
+author is working on, which by \cref{cor:clustered} raises the conflict rate
+and argues for fewer, longer tasks over many short ones. Second,
+\cref{alg:settle} cannot settle formulas, since their printed form shares no
+letters with their source; for those, SyncTeX's lines are kept and the excerpt
+shows the whole display. Third, an agent that cannot ask for permission, such
+as a headless command line, must be restricted in advance; Papilot runs such
+agents so that they edit only the task's worktree, which also means they cannot
+compile or test their own changes.
+
+\subsection{Conclusion}
+
+Papilot treats agent editing as a sequence of reviewable rounds. Isolation
+makes proposals safe, typeset review makes them legible, and explicit
+acceptance keeps the author in charge of the paper. The models in this paper
+make those properties checkable: compatible edits commute and rebase
+(\cref{prop:commute,lem:tp1}), tasks need few rounds
+(\cref{prop:rounds,cor:rounds}), undo never recompiles
+(\cref{prop:undo-build}), per-word text bounds the selection error
+(\cref{thm:per-word}), and partial commits keep unrelated staged work intact
+(\cref{prop:partial}). They also give the reader something worth reviewing.

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "papilot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A Cursor-like workspace for your papers: annotate and review PDFs directly without ever touching LaTeX.",
+  "keywords": [
+    "latex",
+    "pdf",
+    "diff",
+    "review",
+    "ai",
+    "agent",
+    "codex",
+    "claude",
+    "antigravity",
+    "writing",
+    "academic",
+    "manuscript"
+  ],
+  "homepage": "https://github.com/cu1ch3n/papilot#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cu1ch3n/papilot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cu1ch3n/papilot/issues"
+  },
+  "license": "MIT",
+  "author": "Cui Chen",
+  "type": "module",
+  "bin": {
+    "papilot": "bin/papilot.mjs"
+  },
+  "files": [
+    "bin",
+    "src/server",
+    "src/shared.ts",
+    "src/notes.ts",
+    "dist",
+    "scripts/demo.ts",
+    "scripts/service.ts",
+    "examples/papilot-paper",
+    "vendor/latex-review/src",
+    "vendor/latex-review/dist",
+    "vendor/latex-review/package.json",
+    "vendor/latex-review/package-lock.json",
+    "vendor/latex-review/LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/server/main.ts",
+    "start": "tsx src/server/main.ts",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "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",
+    "service:install": "tsx scripts/service.ts install",
+    "service:stop": "tsx scripts/service.ts stop",
+    "test:ui": "npm run build && node scripts/check-ui.mjs",
+    "prepack": "npm run build && npm run setup:review"
+  },
+  "dependencies": {
+    "@fastify/compress": "^9.2.2",
+    "@fastify/static": "^10.1.7",
+    "commander": "^15.0.0",
+    "diff": "^9.0.0",
+    "fastify": "^5.12.7",
+    "mupdf": "^1.28.1",
+    "proper-lockfile": "^4.1.2",
+    "tsx": "^4.23.15"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.311",
+    "@openai/codex": "0.164.0",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "pdfjs-dist": "^6.4.299",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5"
+  }
+}

package/scripts/demo.ts

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { DATA, ROOT } from '../src/server/paths.ts';
+import { Store } from '../src/server/store.ts';
+import { Workspace } from '../src/server/workspace.ts';
+
+// The example is Papilot's own README written as a paper, with plenty of
+// mathematics to review; it is copied into its own Git repository.
+const folder = path.join(DATA, 'example-paper');
+if (!fs.existsSync(folder)) {
+  fs.cpSync(path.join(ROOT, 'examples/papilot-paper'), folder, { recursive: true });
+  execFileSync('git', ['init', '-q', folder]);
+  execFileSync('git', ['-C', folder, 'add', '.']);
+  execFileSync('git', ['-C', folder, '-c', 'user.name=Papilot Example', '-c', 'user.email=papilot@localhost', 'commit', '-qm', 'Add example paper']);
+}
+const store = new Store(path.join(DATA, 'papilot.sqlite'));
+const workspace = new Workspace(store);
+const project = await workspace.addProject(folder, 'Papilot paper');
+console.log(`Example paper ready: ${project.name} (${folder})`);
+store.close();