chore(release): prep v0.1.0 with LICENSE, env example and agent undo test

- Add LICENSE (CC-BY 4.0) aligned with the upstream research-article-template
- Complete backend/.env.example to cover every env var consumed by the
backend (PORT, DATA_DIR, ENABLE_PDF, OAUTH_*, SPACE_ID/SPACE_HOST,
HF_DATASET_ID, HF_TOKEN, OPENROUTER_API_KEY/MODEL, PUBLISH_BASE_URL)
- Extract createAgentBatch() helper from useAgentChat into
frontend/src/editor/agent-undo-batch.ts (pure module, no React) and add
the P0 5.3.1 test from docs/TESTS.md: 3 chained agent edits
(replaceSelection + applyDiff + updateFrontmatter style) revert with a
single Cmd+Z, while the previous user edit stays untouched
- Refresh README known-debt list to reflect the new coverage

Made-with: Cursor

LICENSE

@@ -0,0 +1,33 @@
+Creative Commons Attribution 4.0 International License
+
+Copyright (c) 2026 Thibaud Frere
+
+This work is licensed under the Creative Commons Attribution 4.0 International License.
+To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/
+or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+You are free to:
+
+    Share — copy and redistribute the material in any medium or format
+    Adapt — remix, transform, and build upon the material for any purpose, even commercially.
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+Under the following terms:
+
+    Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+    No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+Notices:
+
+    You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+
+    No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+---
+
+For the source code and technical implementation:
+- The source code is available at: https://huggingface.co/spaces/tfrere/research-article-template-editor
+- This project builds on the research-article-template (https://github.com/huggingface/research-article-template) and inherits its visual design and CSS foundation
+- Dependencies and third-party libraries maintain their respective licenses

README.md

@@ -169,7 +169,7 @@ See [`docs/TESTS.md`](docs/TESTS.md) for the current strategy and gaps.
 
 These are tracked explicitly so new contributors don't trip on them:
 
-- **`useAgentChat` / `useEmbedChat` still lack dedicated unit tests**; the rest of the stores (frontmatter, comments, embeds) are now covered.
+- **`useEmbedChat` still lacks dedicated unit tests**; the rest of the stores (frontmatter, comments, embeds) and the agent undo batching primitive are now covered.
 - **Bundle size warning**: the frontend bundle is over the 500 kB Vite warning threshold. Code-splitting the Mermaid / KaTeX / D3 stacks via dynamic imports would help.
 - **`addToolOutput` typing**: the ai-sdk v6 `ChatAddToolOutputFunction` is a generic over the tool name union. We currently cast to a plain signature at the two call sites because we don't export a typed tool registry yet.
 - **`backend/src/publisher/html-renderer.ts` is ~1000 LOC**: a per-node-type registry would make it more maintainable.

backend/.env.example

@@ -1,7 +1,93 @@
-# OAuth - Create an app at https://huggingface.co/settings/connected-applications
-# Set redirect URI to: http://localhost:8080/auth/callback
+# =============================================================================
+# Research Article Template Editor - Backend environment variables
+# =============================================================================
+# Copy this file to backend/.env and fill in the values you need.
+# All variables are optional unless stated otherwise.
+# See docs/SPECIFICATION.md §6.3 for the full reference.
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+
+# HTTP listen port. Defaults to 8080.
+# PORT=8080
+
+# Where documents, uploads and published bundles are stored on disk.
+# Defaults to ./data (relative to the backend cwd).
+# DATA_DIR=./data
+
+# Toggle Playwright-based PDF + thumbnail generation. Set to "false" to disable
+# PDF export (useful in environments without a browser).
+# ENABLE_PDF=true
+
+# -----------------------------------------------------------------------------
+# Hugging Face OAuth (login + write-access check)
+# -----------------------------------------------------------------------------
+# Required to enforce auth on the editor. When OAUTH_CLIENT_ID and
+# OAUTH_CLIENT_SECRET are unset, OAuth is disabled and every visitor can edit
+# (useful for local dev).
+#
+# Create an OAuth app at https://huggingface.co/settings/connected-applications
+# and set the redirect URI to:
+#   - http://localhost:8080/auth/callback   (local dev)
+#   - https://<SPACE_HOST>/auth/callback    (HF Space)
+
 OAUTH_CLIENT_ID=
 OAUTH_CLIENT_SECRET=
 
-# AI model routing
+# Space-scoped OAuth requires "manage-repos" to read/write the dataset that
+# backs persistence. Defaults to "openid profile" when unset, which is enough
+# for login-only flows but cannot persist documents to a HF dataset.
+# OAUTH_SCOPES=openid profile manage-repos
+
+# -----------------------------------------------------------------------------
+# HF Space context (auto-injected by HF Spaces, set manually for local dev)
+# -----------------------------------------------------------------------------
+
+# Identifies the Space (e.g. "tfrere/research-article-template-editor").
+# Auto-set by HF Spaces. Drives the default dataset id and enables OAuth +
+# secure cookies in production. Leave empty for local dev.
+# SPACE_ID=
+
+# HTTPS host of the deployed Space (e.g. "tfrere-research-article-template-editor.hf.space").
+# Auto-set by HF Spaces. Used to build the OAuth redirect URI.
+# SPACE_HOST=
+
+# -----------------------------------------------------------------------------
+# Hugging Face dataset persistence
+# -----------------------------------------------------------------------------
+# Documents (.yjs), uploads and published bundles are pushed to a HF dataset so
+# they survive Space restarts.
+
+# Override the dataset id. Defaults to "${SPACE_ID}-data" when SPACE_ID is set.
+# Example: HF_DATASET_ID=tfrere/research-article-template-editor-data
+# HF_DATASET_ID=
+
+# Server-side fallback HF token. Used when no user OAuth token is present yet
+# (e.g. before the first login). Optional - the editor caches the last
+# authenticated user's OAuth token for background dataset writes.
+# Generate one at https://huggingface.co/settings/tokens with "Write" scope.
+# HF_TOKEN=
+
+# -----------------------------------------------------------------------------
+# AI features (chat panel + embed studio)
+# -----------------------------------------------------------------------------
+# Required to enable the AI assistant. The chat panel and embed studio are
+# disabled silently when OPENROUTER_API_KEY is unset.
+# Get a key at https://openrouter.ai/keys
+
 OPENROUTER_API_KEY=
+
+# Override the default model id used by the chat agent. The list of supported
+# models is in backend/src/agent/chat.ts (AVAILABLE_MODELS).
+# Defaults to "anthropic/claude-sonnet-4".
+# OPENROUTER_MODEL=anthropic/claude-sonnet-4
+
+# -----------------------------------------------------------------------------
+# Publishing
+# -----------------------------------------------------------------------------
+
+# Absolute base URL injected into the published HTML (canonical URL,
+# OpenGraph, etc.). Defaults to http://127.0.0.1:${PORT}.
+# Example: PUBLISH_BASE_URL=https://tfrere-research-article-template-editor.hf.space
+# PUBLISH_BASE_URL=

frontend/src/editor/agent-undo-batch.ts

@@ -0,0 +1,53 @@
+import type { UndoManager } from "yjs";
+
+/**
+ * Helpers that bracket a sequence of AI-agent edits so they collapse into a
+ * single undo step.
+ *
+ * Yjs UndoManager merges successive transactions that happen within the
+ * `captureTimeout` window (500ms by default). `stopCapturing()` forces the
+ * next transaction to start a fresh undo item, which we use as a *boundary
+ * marker*:
+ *
+ * - `startAgentBatch()` is called once at the first tool call of a turn.
+ *   It separates the previous user edit from the agent batch.
+ * - `endAgentBatch()` is called when the model finishes streaming.
+ *   It separates the agent batch from the user's next edits.
+ *
+ * Between the two markers, every Yjs-backed mutation issued by the agent
+ * (replaceSelection, applyDiff, updateFrontmatter, ...) merges into one
+ * undo item so a single `Cmd+Z` reverts the entire turn.
+ *
+ * The functions are no-ops when the manager is unavailable (early in the
+ * editor lifecycle) or when the batch is already (in)active, which keeps
+ * call sites trivial.
+ */
+export interface AgentBatchHandle {
+  startAgentBatch(): void;
+  endAgentBatch(): void;
+  isActive(): boolean;
+}
+
+export function createAgentBatch(
+  undoManager: UndoManager | null | undefined,
+): AgentBatchHandle {
+  let active = false;
+
+  return {
+    startAgentBatch() {
+      if (undoManager && !active) {
+        undoManager.stopCapturing();
+        active = true;
+      }
+    },
+    endAgentBatch() {
+      if (undoManager && active) {
+        undoManager.stopCapturing();
+        active = false;
+      }
+    },
+    isActive() {
+      return active;
+    },
+  };
+}

frontend/src/hooks/useAgentChat.ts

@@ -9,6 +9,7 @@ import type { UndoManager } from "yjs";
 import type { UIMessage } from "ai";
 import type { FrontmatterStore } from "../editor/frontmatter/frontmatter-store";
 import { executeTiptapCommand, TIPTAP_TOOL_NAMES } from "../editor/agent-executor";
+import { createAgentBatch } from "../editor/agent-undo-batch";
 
 interface UseAgentChatOptions {
   editor: Editor | null;
@@ -23,7 +24,10 @@ const transport = new DefaultChatTransport({ api: "/api/chat" });
 
 export function useAgentChat({ editor, undoManager, frontmatterStore, modelRef, initialMessages, onMessagesChange }: UseAgentChatOptions) {
   const pendingSelectionRef = useRef<{ from: number; to: number } | null>(null);
-  const agentBatchActiveRef = useRef(false);
+  const agentBatchRef = useRef(createAgentBatch(undoManager));
+  useEffect(() => {
+    agentBatchRef.current = createAgentBatch(undoManager);
+  }, [undoManager]);
   const [input, setInput] = useState("");
   const onMessagesChangeRef = useRef(onMessagesChange);
   onMessagesChangeRef.current = onMessagesChange;
@@ -53,18 +57,12 @@ export function useAgentChat({ editor, undoManager, frontmatterStore, modelRef,
    * merged into one undo step until endAgentBatch() is called.
    */
   const startAgentBatch = useCallback(() => {
-    if (undoManager && !agentBatchActiveRef.current) {
-      undoManager.stopCapturing();
-      agentBatchActiveRef.current = true;
-    }
-  }, [undoManager]);
+    agentBatchRef.current.startAgentBatch();
+  }, []);
 
   const endAgentBatch = useCallback(() => {
-    if (undoManager && agentBatchActiveRef.current) {
-      undoManager.stopCapturing();
-      agentBatchActiveRef.current = false;
-    }
-  }, [undoManager]);
+    agentBatchRef.current.endAgentBatch();
+  }, []);
 
   /**
    * Extract all text from the ProseMirror document as a flat string,

frontend/tests/agent-undo-batch.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Agent Undo Batch Tests
+ *
+ * Covers `docs/TESTS.md` 5.3 - undo batching for AI-agent edits.
+ *
+ * The agent runs multiple tool calls per turn (replaceSelection, applyDiff,
+ * updateFrontmatter, ...). Each tool call triggers one or more Yjs
+ * transactions. Without batching, the user would have to press Cmd+Z three
+ * times to revert a single agent turn. We bracket the turn with
+ * `startAgentBatch()` / `endAgentBatch()` so it collapses into one undo step.
+ *
+ * These tests target `createAgentBatch` against a real `Y.Doc` +
+ * `UndoManager`, mirroring what `useAgentChat` wires at runtime. We don't
+ * spin up TipTap or React because the contract being verified ("3
+ * collaborative edits inside the batch revert with a single undo()") is
+ * purely a Yjs concern.
+ */
+import { describe, it, expect } from "vitest";
+import * as Y from "yjs";
+import { createAgentBatch } from "../src/editor/agent-undo-batch";
+
+const AGENT_ORIGIN = Symbol("agent");
+const USER_ORIGIN = Symbol("user");
+
+interface Fixture {
+  ydoc: Y.Doc;
+  body: Y.XmlFragment;
+  frontmatter: Y.Map<unknown>;
+  undoManager: Y.UndoManager;
+  batch: ReturnType<typeof createAgentBatch>;
+}
+
+function makeFixture(): Fixture {
+  const ydoc = new Y.Doc();
+  const body = ydoc.getXmlFragment("default");
+  const frontmatter = ydoc.getMap("frontmatter");
+
+  // Mirror `@tiptap/extension-collaboration`'s setup: one UndoManager that
+  // watches both the doc body and the frontmatter map, so a single undo()
+  // can revert text edits AND metadata mutations together.
+  const undoManager = new Y.UndoManager([body, frontmatter], {
+    captureTimeout: 500,
+    trackedOrigins: new Set([AGENT_ORIGIN, USER_ORIGIN]),
+  });
+
+  return { ydoc, body, frontmatter, undoManager, batch: createAgentBatch(undoManager) };
+}
+
+/**
+ * Helper that mimics a TipTap text insertion: appends a paragraph element
+ * containing the given text to the document body.
+ */
+function appendParagraph(ydoc: Y.Doc, body: Y.XmlFragment, text: string, origin: symbol) {
+  ydoc.transact(() => {
+    const p = new Y.XmlElement("paragraph");
+    p.insert(0, [new Y.XmlText(text)]);
+    body.push([p]);
+  }, origin);
+}
+
+/**
+ * Helper that mimics agent `applyDiff`: rewrites the text content of a
+ * specific paragraph in place.
+ */
+function rewriteParagraph(
+  ydoc: Y.Doc,
+  body: Y.XmlFragment,
+  index: number,
+  newText: string,
+  origin: symbol,
+) {
+  ydoc.transact(() => {
+    const p = body.get(index) as Y.XmlElement;
+    const t = p.get(0) as Y.XmlText;
+    t.delete(0, t.length);
+    t.insert(0, newText);
+  }, origin);
+}
+
+function bodyAsText(body: Y.XmlFragment): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const node = body.get(i) as Y.XmlElement;
+    const t = node.get(0) as Y.XmlText;
+    out.push(t.toString());
+  }
+  return out;
+}
+
+describe("agent-undo-batch — primitive contract", () => {
+  it("startAgentBatch + endAgentBatch are idempotent", () => {
+    const { batch } = makeFixture();
+
+    expect(batch.isActive()).toBe(false);
+    batch.startAgentBatch();
+    expect(batch.isActive()).toBe(true);
+
+    // Calling start again is a no-op.
+    batch.startAgentBatch();
+    expect(batch.isActive()).toBe(true);
+
+    batch.endAgentBatch();
+    expect(batch.isActive()).toBe(false);
+
+    // Calling end again is a no-op.
+    batch.endAgentBatch();
+    expect(batch.isActive()).toBe(false);
+  });
+
+  it("is a noop when the UndoManager is null", () => {
+    const batch = createAgentBatch(null);
+    expect(() => batch.startAgentBatch()).not.toThrow();
+    expect(() => batch.endAgentBatch()).not.toThrow();
+    expect(batch.isActive()).toBe(false);
+  });
+});
+
+describe("agent-undo-batch — 5.3.1 batched undo (P0)", () => {
+  it("reverts 3 chained agent edits with a single undo()", () => {
+    const { ydoc, body, frontmatter, undoManager, batch } = makeFixture();
+
+    // Simulate a prior user edit that should NOT be touched by the agent's
+    // single undo step. We give it a separate origin so its capture window
+    // is closed before the agent batch starts.
+    appendParagraph(ydoc, body, "User wrote this first.", USER_ORIGIN);
+    expect(bodyAsText(body)).toEqual(["User wrote this first."]);
+
+    // --- Agent turn ---------------------------------------------------------
+    batch.startAgentBatch();
+
+    // Tool 1: replaceSelection-style rewrite of the existing paragraph.
+    rewriteParagraph(ydoc, body, 0, "User wrote this first. (refined by agent)", AGENT_ORIGIN);
+
+    // Tool 2: insertAtCursor-style append of a new paragraph.
+    appendParagraph(ydoc, body, "Agent added a follow-up.", AGENT_ORIGIN);
+
+    // Tool 3: updateFrontmatter-style metadata change.
+    ydoc.transact(() => {
+      frontmatter.set("title", "New title from agent");
+    }, AGENT_ORIGIN);
+
+    batch.endAgentBatch();
+
+    // Sanity check: all three changes landed.
+    expect(bodyAsText(body)).toEqual([
+      "User wrote this first. (refined by agent)",
+      "Agent added a follow-up.",
+    ]);
+    expect(frontmatter.get("title")).toBe("New title from agent");
+
+    // --- Undo once ----------------------------------------------------------
+    undoManager.undo();
+
+    // All three agent edits revert together; the user paragraph stays.
+    expect(bodyAsText(body)).toEqual(["User wrote this first."]);
+    expect(frontmatter.get("title")).toBeUndefined();
+  });
+
+  it("does not lump the previous user edit into the agent step", () => {
+    const { ydoc, body, undoManager, batch } = makeFixture();
+
+    // Two distinct user edits, then an agent batch.
+    appendParagraph(ydoc, body, "First user paragraph.", USER_ORIGIN);
+    appendParagraph(ydoc, body, "Second user paragraph.", USER_ORIGIN);
+
+    batch.startAgentBatch();
+    appendParagraph(ydoc, body, "Agent paragraph.", AGENT_ORIGIN);
+    batch.endAgentBatch();
+
+    expect(bodyAsText(body)).toEqual([
+      "First user paragraph.",
+      "Second user paragraph.",
+      "Agent paragraph.",
+    ]);
+
+    // First undo: only the agent edit reverts.
+    undoManager.undo();
+    expect(bodyAsText(body)).toEqual([
+      "First user paragraph.",
+      "Second user paragraph.",
+    ]);
+  });
+});