Dev

[tutoratlas]

What Changed

Why

UI Changes

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

High Risk
Large cross-cutting change including a new desktop appId, new local persistence, and Electron PDF rendering; mistakes could affect updates, data loss, or desktop stability.

Overview
Repositions the fork as TutorAtlas: user-facing copy, splash/titles, desktop productName, and packaging now use com.tutoratlas.app / TutorAtlas artifact names (may break continuity with prior T3 Code installs).

Adds a Students surface: sidebar link to /students, roster CRUD UI, and persistence through getStudents/setStudents (desktop students.json via DesktopStudents, web localStorage fallback).

Ships a materials + PDF path on desktop: ensureStudentWorkspace scaffolds students/<slug>/, markdown is turned into print HTML, DesktopPdfRenderer uses a hidden BrowserWindow + printToPDF, and RenderPdfButton is wired into markdown file preview. Materials threads hide PR/git chrome in the sidebar when worktreePath contains /students/.

Also adds extensive .plans/ specs (licensing, Atlas roadmap, manual test guides), .gitignore entries for Auto Claude artifacts, and an E2E-VERIFICATION-RESULTS checklist doc.

^{Reviewed by Cursor Bugbot for commit 7dbfd81. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Rebrand app from 'T3 Code' to 'TutorAtlas' and add student roster and PDF rendering features

• Renames the application to 'TutorAtlas' across all user-facing strings, build configs, app IDs, artifact names, and assets (icons, favicons, logos) for desktop and web.
• Adds a Students module: new students.ts contracts with schemas for Student, PhoneNumber, SingaporeAddress, and Parent; a DesktopStudents service with atomic JSON persistence; IPC channels; and a /students route with list, detail, create, edit, and delete UI.
• Adds a PDF rendering pipeline: markdownToHtml with embedded fonts and print CSS, a DesktopPdfRenderer service using Electron's printToPDF with atomic writes, IPC wiring, and a RenderPdfButton shown in the markdown file preview panel.
• Adds a DesktopWorkspace service that idempotently creates per-student directories under ~/tutoratlas/workspace/students/<slug> and optionally seeds AGENTS.md; wired into the sidebar's new Students nav entry.
• Risk: the desktop app ID changes from com.t3tools.t3code to com.tutoratlas.app, which will break auto-update continuity for existing installs and change OS-level data directory paths.

^{Macroscope summarized 7dbfd81.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0606bbc1-a675-487d-add5-51364f27c00e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

🟠 High settings/DesktopStudents.ts:41

StudentSchema does not include the optional workspaceFolder field that exists on the Student contract. When setRegistry encodes a Student object that has workspaceFolder set, encodeStudentRegistryDocumentJson silently drops that field from the persisted JSON, and the next getRegistry read loses the saved workspace path for every student. Consider adding the missing workspaceFolder field to StudentSchema so it round-trips through encode/decode.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/settings/DesktopStudents.ts around line 41:

`StudentSchema` does not include the optional `workspaceFolder` field that exists on the `Student` contract. When `setRegistry` encodes a `Student` object that has `workspaceFolder` set, `encodeStudentRegistryDocumentJson` silently drops that field from the persisted JSON, and the next `getRegistry` read loses the saved workspace path for every student. Consider adding the missing `workspaceFolder` field to `StudentSchema` so it round-trips through encode/decode.

[macroscopeapp]

🟠 High students/StudentDetail.tsx:87

handleGenerateMaterials passes defaultProjectRef to handleNewThread, but defaultProjectRef comes from useHandleNewThread() which selects the first project across all environments via selectProjectsAcrossEnvironments. When a remote environment's project is ordered first, the thread is created in that remote environment while worktreePath points to a local desktop-only folder from window.desktopBridge.ensureStudentWorkspace. The remote runtime is then asked to use a path that does not exist on it, so the materials session cannot run. The project should be selected from the local desktop environment specifically, not whichever environment happens to be first.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/students/StudentDetail.tsx around line 87:

`handleGenerateMaterials` passes `defaultProjectRef` to `handleNewThread`, but `defaultProjectRef` comes from `useHandleNewThread()` which selects the first project across *all* environments via `selectProjectsAcrossEnvironments`. When a remote environment's project is ordered first, the thread is created in that remote environment while `worktreePath` points to a local desktop-only folder from `window.desktopBridge.ensureStudentWorkspace`. The remote runtime is then asked to use a path that does not exist on it, so the materials session cannot run. The project should be selected from the local desktop environment specifically, not whichever environment happens to be first.

[macroscopeapp]

🟡 Medium pdf/RenderPdfButton.tsx:93

onSuccess?.(pdfPath) is called inside the same try block as renderPdf. If the caller's onSuccess callback throws after the PDF was already created, execution falls into the catch block, which logs Failed to render PDF, shows an error toast, and invokes onError — even though rendering succeeded. Wrap the callback in its own try/catch so its errors aren't misattributed as render failures.

Suggested change

	onSuccess?.(pdfPath);
	try {
	onSuccess?.(pdfPath);
	} catch (callbackError) {
	console.error("onSuccess callback threw:", callbackError);
	}

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/pdf/RenderPdfButton.tsx around line 93:

`onSuccess?.(pdfPath)` is called inside the same `try` block as `renderPdf`. If the caller's `onSuccess` callback throws after the PDF was already created, execution falls into the `catch` block, which logs `Failed to render PDF`, shows an error toast, and invokes `onError` — even though rendering succeeded. Wrap the callback in its own try/catch so its errors aren't misattributed as render failures.

[macroscopeapp]

🟡 Medium pdf/DesktopPdfRenderer.ts:76

The did-fail-load handler fails the didFinishLoadDeferred for every load failure, but Electron fires this event for subframe and subresource loads too. Since the handler ignores the isMainFrame argument, a broken image or iframe in the HTML rejects the deferred and aborts PDF generation even though the main document loaded successfully and could be printed. Consider checking isMainFrame before failing the deferred.

Suggested change

	const failLoadHandler = (
	_event: Electron.Event,
	errorCode: number,
	errorDescription: string,
	) => {
	void Effect.runSync(
	Deferred.fail(
	didFinishLoadDeferred,
	new DesktopPdfRendererError({
	cause: `Failed to load HTML: ${errorCode} ${errorDescription}`,
	}),
	),
	);
	};
	const failLoadHandler = (
	_event: Electron.Event,
	errorCode: number,
	errorDescription: string,
	_validatedURL: string,
	isMainFrame: boolean,
	) => {
	if (!isMainFrame) return;
	void Effect.runSync(
	Deferred.fail(
	didFinishLoadDeferred,
	new DesktopPdfRendererError({
	cause: `Failed to load HTML: ${errorCode} ${errorDescription}`,
	}),
	),
	);
	};

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/pdf/DesktopPdfRenderer.ts around lines 76-89:

The `did-fail-load` handler fails the `didFinishLoadDeferred` for every load failure, but Electron fires this event for subframe and subresource loads too. Since the handler ignores the `isMainFrame` argument, a broken image or iframe in the HTML rejects the deferred and aborts PDF generation even though the main document loaded successfully and could be printed. Consider checking `isMainFrame` before failing the deferred.

[macroscopeapp]

🟠 High students/StudentForm.tsx:177

The useState initializer at line 177 only runs on mount, so when initialStudent changes while StudentForm stays mounted, the form fields keep the previous student's data. On submit, handleSubmit builds a Student using initialStudent?.id and initialStudent?.createdAt (the new student's identity) but with the stale field values from the old student, overwriting the wrong record. Consider adding a key prop based on the student ID to the StudentForm in the parent so it remounts with fresh state, or syncing formState via a useEffect when initialStudent changes.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/students/StudentForm.tsx around line 177:

The `useState` initializer at line 177 only runs on mount, so when `initialStudent` changes while `StudentForm` stays mounted, the form fields keep the previous student's data. On submit, `handleSubmit` builds a `Student` using `initialStudent?.id` and `initialStudent?.createdAt` (the new student's identity) but with the stale field values from the old student, overwriting the wrong record. Consider adding a `key` prop based on the student ID to the `StudentForm` in the parent so it remounts with fresh state, or syncing `formState` via a `useEffect` when `initialStudent` changes.

[macroscopeapp]

🔴 Critical workspace/DesktopWorkspace.ts:32

ensureStudentWorkspaceImpl builds folderPath by joining workspaceRoot, "students", and slug without validating that slug is a safe directory name. A value like ../outside or an absolute path escapes the students directory, so makeDirectory and writeFileString create directories and files outside the intended workspace tree. Consider rejecting slug values that contain path separators or .. segments before using them in path operations.

Also found in 1 other location(s)

apps/desktop/src/ipc/methods/workspace.ts:24

ensureStudentWorkspace uses input.studentId directly as the filesystem slug, but StudentId only guarantees a trimmed non-empty string. A value like "../other-dir" or "nested/path" will make DesktopWorkspace.ensureStudentWorkspace create folders outside the intended students directory because it does path.join(workspaceRoot, "students", slug). This exposes arbitrary directory creation/traversal via the IPC method.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/workspace/DesktopWorkspace.ts around line 32:

`ensureStudentWorkspaceImpl` builds `folderPath` by joining `workspaceRoot`, `"students"`, and `slug` without validating that `slug` is a safe directory name. A value like `../outside` or an absolute path escapes the `students` directory, so `makeDirectory` and `writeFileString` create directories and files outside the intended workspace tree. Consider rejecting `slug` values that contain path separators or `..` segments before using them in path operations.

Also found in 1 other location(s):
- apps/desktop/src/ipc/methods/workspace.ts:24 -- `ensureStudentWorkspace` uses `input.studentId` directly as the filesystem `slug`, but `StudentId` only guarantees a trimmed non-empty string. A value like `"../other-dir"` or `"nested/path"` will make `DesktopWorkspace.ensureStudentWorkspace` create folders outside the intended `students` directory because it does `path.join(workspaceRoot, "students", slug)`. This exposes arbitrary directory creation/traversal via the IPC method.

[macroscopeapp]

🟡 Medium students/links.ts:33

toE164 returns ${dialCode}${cleanNumber} without stripping a leading national prefix 0 from cleanNumber. When a user enters a domestic number like 0123456789, this produces 600123456789 instead of the valid E.164 form 60123456789, which breaks the WhatsApp and Telegram deep links. Consider removing a leading 0 from cleanNumber before concatenating with the dial code.

Suggested change

	return `${dialCode}${cleanNumber}`;
	const normalized = cleanNumber.replace(/^0+/, "");
	return `${dialCode}${normalized}`;

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/students/links.ts around line 33:

`toE164` returns `${dialCode}${cleanNumber}` without stripping a leading national prefix `0` from `cleanNumber`. When a user enters a domestic number like `0123456789`, this produces `600123456789` instead of the valid E.164 form `60123456789`, which breaks the WhatsApp and Telegram deep links. Consider removing a leading `0` from `cleanNumber` before concatenating with the dial code.

[macroscopeapp]

🟡 Medium students/StudentDetail.tsx:87

handleGenerateMaterials passes worktreePath to handleNewThread but omits envMode, which defaults to "local". The resulting draft thread is tagged as a local session even though it points at a dedicated worktree workspace, so components like GitActionsControl that branch on activeDraftThread.envMode skip worktree-specific behavior. Add envMode: "worktree" to the options so the thread mode matches the workspace.

Suggested change

	await handleNewThread(defaultProjectRef, {
	worktreePath: result.workspacePath,
	});
	await handleNewThread(defaultProjectRef, {
	worktreePath: result.workspacePath,
	envMode: "worktree",
	});

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/students/StudentDetail.tsx around lines 87-89:

`handleGenerateMaterials` passes `worktreePath` to `handleNewThread` but omits `envMode`, which defaults to `"local"`. The resulting draft thread is tagged as a local session even though it points at a dedicated worktree workspace, so components like `GitActionsControl` that branch on `activeDraftThread.envMode` skip worktree-specific behavior. Add `envMode: "worktree"` to the options so the thread mode matches the workspace.

[macroscopeapp]

🟡 Medium pdf/markdownToHtml.ts:36

markdownToHtml emits a full HTML document without a <base> tag or any rebasing of relative src/href URLs. When the desktop renderer loads this document via a data: URL, relative paths like ./diagram.png or ./appendix.md resolve against the data URL itself, so all relative links and images in the exported PDF are broken. Consider accepting a base URL parameter and emitting a <base href="..."> tag in the document <head> so relative paths resolve correctly.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/pdf/markdownToHtml.ts around line 36:

`markdownToHtml` emits a full HTML document without a `<base>` tag or any rebasing of relative `src`/`href` URLs. When the desktop renderer loads this document via a `data:` URL, relative paths like `./diagram.png` or `./appendix.md` resolve against the data URL itself, so all relative links and images in the exported PDF are broken. Consider accepting a base URL parameter and emitting a `<base href="...">` tag in the document `<head>` so relative paths resolve correctly.

[cursor]

Silent student persist failures

High Severity

The persistStudents function silently catches errors, allowing handleSave and handleDelete to update the UI and in-memory state as if persistence succeeded. This desynchronizes the UI from actual persisted data, leading to incorrect displays (e.g., unsaved new students, stale edits, or reappearing deleted students) without user feedback.

 

^{Reviewed by Cursor Bugbot for commit e9add25. Configure here.}

[cursor]

Maps link ignores postal rule

Medium Severity

The googleMapsLink function generates a Google Maps URL for addresses that may be incomplete, as it doesn't require a postalCode. It also includes building and unit in the search query. This can lead to the "Open in Google Maps" button appearing for addresses that are too vague for a useful map search.

 

^{Reviewed by Cursor Bugbot for commit e9add25. Configure here.}

[cursor]

Workspace never seeds AGENTS.md

High Severity

The ensureStudentWorkspace IPC handler, used by the "Generate materials" feature, doesn't pass the agentsMarkdown content to the workspace service. This results in newly created student workspaces lacking the AGENTS.md harness file.

 

^{Reviewed by Cursor Bugbot for commit e9add25. Configure here.}

[cursor]

Invalid phone country wipes roster

High Severity

If students.json contains a legacy or invalid phone country (for example dial code +65 instead of SG), document decode fails and the reader substitutes an empty student list, hiding every stored student until the file is repaired manually.

 

^{Reviewed by Cursor Bugbot for commit e9add25. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

16 blocking correctness issues found. Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Agent commit log committed

Low Severity

A commit-message.txt file, an auto-claude verification log, was added to the repository root. This isn't application source or user documentation, and its presence in the tree could confuse contributors or impact release tooling.

 

^{Reviewed by Cursor Bugbot for commit 5059eb2. Configure here.}

[cursor]

SSH prompt mixed product names

Low Severity

The SSH password dialog displays inconsistent product naming. The dialog title and description refer to "T3 needs your SSH password", but then state credentials are not saved by "TutorAtlas", which is confusing for users.

 

^{Reviewed by Cursor Bugbot for commit 5059eb2. Configure here.}

[macroscopeapp]

🟡 Medium atlas/01-branding.md:79

The generator instructions hard-code the pnpm virtual-store path node_modules/.pnpm/sharp@0.34.5/node_modules/sharp. pnpm's .pnpm directory names are not stable — they change when sharp is upgraded and can include peer-resolution suffixes. Following this plan as written makes node scripts/gen-brand-assets.mjs throw MODULE_NOT_FOUND as soon as the lockfile or pnpm layout changes, breaking the promised re-runnable asset generation. Consider resolving sharp dynamically (e.g. globbing node_modules/.pnpm/sharp@*) or adding it as a proper devDependency instead.

  const require = createRequire(import.meta.url);
-  const sharp = require(`${repoRoot}/node_modules/.pnpm/sharp@0.34.5/node_modules/sharp`);
+  const sharpDir = fs.readdirSync(`${repoRoot}/node_modules/.pnpm`).find(d => d.startsWith("sharp@"));
+  const sharp = require(`${repoRoot}/node_modules/.pnpm/${sharpDir}/node_modules/sharp`);

🤖 Copy this AI Prompt to have your agent fix this:

In file @.plans/atlas/01-branding.md around lines 79-82:

The generator instructions hard-code the pnpm virtual-store path `node_modules/.pnpm/sharp@0.34.5/node_modules/sharp`. pnpm's `.pnpm` directory names are not stable — they change when `sharp` is upgraded and can include peer-resolution suffixes. Following this plan as written makes `node scripts/gen-brand-assets.mjs` throw `MODULE_NOT_FOUND` as soon as the lockfile or pnpm layout changes, breaking the promised re-runnable asset generation. Consider resolving `sharp` dynamically (e.g. globbing `node_modules/.pnpm/sharp@*`) or adding it as a proper devDependency instead.

[macroscopeapp]

🟠 High scripts/build-desktop-artifact.ts:751

The build config now sets appId: "com.tutoratlas.app", but the runtime still hard-codes the old AppUserModelID com.t3tools.t3code in apps/desktop/src/app/DesktopEnvironment.ts and DesktopAppIdentity.ts. On Windows, Electron requires the installer-registered AppUserModelID to match the one the running app sets via setAppUserModelId. This mismatch breaks toast notifications and shell integration on packaged Windows builds because the app starts under a different ID than the installer registered. Update the runtime AppUserModelID in those files to match com.tutoratlas.app, or make both read from a single shared constant.

🤖 Copy this AI Prompt to have your agent fix this:

In file @scripts/build-desktop-artifact.ts around line 751:

The build config now sets `appId: "com.tutoratlas.app"`, but the runtime still hard-codes the old AppUserModelID `com.t3tools.t3code` in `apps/desktop/src/app/DesktopEnvironment.ts` and `DesktopAppIdentity.ts`. On Windows, Electron requires the installer-registered AppUserModelID to match the one the running app sets via `setAppUserModelId`. This mismatch breaks toast notifications and shell integration on packaged Windows builds because the app starts under a different ID than the installer registered. Update the runtime AppUserModelID in those files to match `com.tutoratlas.app`, or make both read from a single shared constant.

[macroscopeapp]

🟡 Medium files/FilePreviewPanel.tsx:740

RenderPdfButton is shown whenever renderMarkdown is active, but the condition does not check file.data.truncated. When the file exceeds the preview byte limit, file.data.contents holds only a prefix, so clicking the button renders a PDF from an incomplete document while reporting success. Add !file.data.truncated to the render condition so the button is hidden for truncated files.

Suggested change

	{isMarkdown && renderMarkdown && file.data && derivedOutputPath ? (
	{isMarkdown && renderMarkdown && file.data && !file.data.truncated && derivedOutputPath ? (

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/web/src/components/files/FilePreviewPanel.tsx around line 740:

`RenderPdfButton` is shown whenever `renderMarkdown` is active, but the condition does not check `file.data.truncated`. When the file exceeds the preview byte limit, `file.data.contents` holds only a prefix, so clicking the button renders a PDF from an incomplete document while reporting success. Add `!file.data.truncated` to the render condition so the button is hidden for truncated files.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

There are 9 total unresolved issues (including 6 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7dbfd81. Configure here.}

[cursor]

PDF path ignores Windows separators

Medium Severity

The derivedOutputPath for PDF generation constructs paths using hardcoded forward slashes. This can lead to incorrect or mixed path separators on Windows, unlike other file path resolutions in the panel that correctly normalize for the operating system. This mismatch affects the reliability of saving or opening PDF output.

 

^{Reviewed by Cursor Bugbot for commit 7dbfd81. Configure here.}

[cursor]

Render PDF hidden in source view

Medium Severity

The RenderPdfButton for markdown files is only visible when the file is in rendered preview mode. Markdown files default to the source editor, requiring users to toggle the view to access PDF rendering, despite the content being available in source mode.

 

^{Reviewed by Cursor Bugbot for commit 7dbfd81. Configure here.}

[cursor]

Partial PDF from truncated files

Medium Severity

When a file exceeds the preview size limit, the UI shows a banner that only the first 1 MB is loaded, but Render PDF can still run in rendered mode using that truncated file.data.contents. The deliverable PDF can silently omit the rest of the document with no block or warning on the action.

 

^{Reviewed by Cursor Bugbot for commit 7dbfd81. Configure here.}