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 (branding, data paths, workspace cwd, new persistence/IPC/PDF) can break existing installs, updates, and stored student data locations; PDF rendering and filesystem deletes are security- and data-loss-sensitive surfaces.

Overview
This PR pivots the fork toward TutorAtlas: user-facing branding and desktop productName move from T3 Code to TutorAtlas, app data/env shifts from T3CODE_HOME / .t3 to TUTORATLAS_HOME / .tutoratlas, and the embedded server backendCwd / workspaceRoot default to ~/tutoratlas with T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD enabled so launch can auto-open a single workspace project.

Students land as a first-class feature: @t3tools/contracts student schemas (optional workspaceFolder, deriveStudentSlug), DesktopStudents atomic JSON registry + get/set IPC, preload bridge methods, and the web Students route/UI (form validation, phone country codes, deep links). DesktopWorkspace creates students/<slug>/ under the workspace (optional AGENTS.md), bootstraps .atlas/skills, and exposes ensure/delete/open-path IPC with path checks on delete.

PDF materials: DesktopPdfRenderer renders HTML via a hidden BrowserWindow + printToPDF with temp-then-rename writes; renderMarkdownToPdf / openPath IPC and ElectronShell.openPath wire the web preview RenderPdfButton path described in the plans. Sidebar isMaterialsThread hides PR/git chrome for threads under /students/.

Also adds extensive .plans/ Atlas roadmap docs, .gitignore entries for Auto Claude, and an E2E verification write-up for the materials/PDF checklist—not runtime behavior by itself.

^{Reviewed by Cursor Bugbot for commit 337bb04. 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 product from T3 Code to TutorAtlas across all user-facing strings, config keys (T3CODE_HOME → TUTORATLAS_HOME, t3Home → tutoratlasHome), environment paths (~/.t3 → ~/.tutoratlas), app IDs, and build artifact names.
• Adds a full student management system: Student schema in contracts, desktop DesktopStudents service for atomic on-disk persistence at environment.studentRegistryPath, IPC channels for get/set, browser localStorage fallback, and a /students route with list/detail/form UI.
• Adds per-student workspace management via DesktopWorkspace: creates <workspaceRoot>/students/<slug> directories, seeds AGENTS.md, bootstraps .atlas/skills/ on startup, and supports secure deletion.
• Adds a PDF rendering pipeline: markdownToHtml embeds base64 woff2 fonts (DM Sans Variable, Source Serif 4 Variable) and print CSS into a full HTML document, DesktopPdfRenderer renders it via an offscreen Electron BrowserWindow with atomic file write, and RenderPdfButton exposes this in the markdown preview UI.
• Adds a gen-brand-assets script that generates ICO, ICNS, and PNG icon assets from assets/atlas/logo.svg using sharp.
• Risk: backendCwd now points to workspaceRoot (~/tutoratlas) instead of homeDirectory/appRoot, which changes where the backend server is launched from.

^{Macroscope summarized 337bb04.}

[cursor]

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

There are 12 total unresolved issues (including 5 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 337bb04. Configure here.}

[cursor]

Roster deleted after failed workspace

High Severity

When deleting a student, the application removes them from the roster and persists this change even if the deleteStudentWorkspace call fails. This can leave student workspace files on disk while the UI shows the student as deleted, leading to an inconsistent state.

 

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

[cursor]

Two delete confirmation dialogs

Medium Severity

Deleting a student with an associated workspace folder triggers two native confirmation dialogs. The first dialog omits mention of the workspace folder, while the second explicitly asks about deleting it, leading to redundant confirmation for users.

 

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

[cursor]

Legacy app data not migrated

High Severity

The app's base directory for user state now defaults to ~/.tutoratlas (or TUTORATLAS_HOME), no longer falling back to the previous ~/.t3 (or T3CODE_HOME). Upgraded installs don't migrate existing data, so rosters, settings, and tokens appear empty.

 

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

[cursor]

Project context menu disabled wrongly

Low Severity

The handleProjectButtonContextMenu for project rows now immediately returns, preventing the custom context menu and its actions (like rename or delete) from appearing. This also allows the browser's default context menu to show.

 

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

[cursor]

Manual project reorder always disabled

Medium Severity

The sidebar project list always renders the non-draggable branch because the condition was changed from isManualProjectSorting to literal false. Users who set manual project sort in settings can no longer drag-reorder workspace projects.

 

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

[cursor]

Delete wipes all student folders

High Severity

The delete path guard treats a resolved path equal to the shared students directory as valid, then recursively removes it. A workspaceFolder value of students (allowed by the contract) can delete every student workspace under the tutor root, not one slug folder.

 

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

[macroscopeapp]

🟡 Medium scripts/electron-launcher.mjs:107

The diff renames the exported env var on line 107 from T3CODE_HOME to TUTORATLAS_HOME, but LAUNCHER_VERSION was not bumped. buildMacLauncher() reuses an existing cached bundle whenever metadata.json matches, and expectedMetadata only includes launcherVersion, source bundle mtimes, icon mtime, bundle id, and protocol schemes — not the generated script contents or env var names. Developers who already have .electron-runtime/T3 Code (Dev).app will keep launching the old wrapper that still exports T3CODE_HOME, while the desktop app now reads TUTORATLAS_HOME. On those machines the app silently falls back to the default home directory instead of the configured one until the cached launcher is manually deleted. Bump LAUNCHER_VERSION so the cached launcher is invalidated and regenerated with the new env var name.

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

In file @apps/desktop/scripts/electron-launcher.mjs around line 107:

The diff renames the exported env var on line 107 from `T3CODE_HOME` to `TUTORATLAS_HOME`, but `LAUNCHER_VERSION` was not bumped. `buildMacLauncher()` reuses an existing cached bundle whenever `metadata.json` matches, and `expectedMetadata` only includes `launcherVersion`, source bundle mtimes, icon mtime, bundle id, and protocol schemes — not the generated script contents or env var names. Developers who already have `.electron-runtime/T3 Code (Dev).app` will keep launching the old wrapper that still exports `T3CODE_HOME`, while the desktop app now reads `TUTORATLAS_HOME`. On those machines the app silently falls back to the default home directory instead of the configured one until the cached launcher is manually deleted. Bump `LAUNCHER_VERSION` so the cached launcher is invalidated and regenerated with the new env var name.

[macroscopeapp]

🟡 Medium workspace/DesktopWorkspace.ts:84

The security check uses Effect.die(...) for an invalid path, but deleteStudentWorkspace is wrapped only with Effect.mapError(...). Defects are not caught by mapError, so an out-of-tree workspaceFolder such as ../other terminates the effect instead of surfacing as a DesktopWorkspaceError. Consider using Effect.fail(...) with a DesktopWorkspaceError so the invalid-path condition is handled as a normal error.

Suggested change

	return yield* Effect.die(
	`Security: Path '${realPath}' is not strictly inside students directory '${realStudentsDir}'`,
	);
	}
	return yield* Effect.fail(
	new DesktopWorkspaceError({
	cause: new PlatformError.PlatformError({ reason: "AccessDenied", error: new Error(`Security: Path '${realPath}' is not strictly inside students directory '${realStudentsDir}'`) }),
	context: "to delete student workspace",
	}),
	);

Also found in 1 other location(s)

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

deleteStudentWorkspace wraps workspace.deleteStudentWorkspace(...) with Effect.match, but the implementation in DesktopWorkspace uses Effect.die(...) when workspaceFolder resolves outside the students directory. Effect.match does not catch defects, so an invalid or malicious workspaceFolder makes this handler reject the IPC call instead of returning the declared { success: false, error } result shape.

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

In file @apps/desktop/src/workspace/DesktopWorkspace.ts around lines 84-87:

The security check uses `Effect.die(...)` for an invalid path, but `deleteStudentWorkspace` is wrapped only with `Effect.mapError(...)`. Defects are not caught by `mapError`, so an out-of-tree `workspaceFolder` such as `../other` terminates the effect instead of surfacing as a `DesktopWorkspaceError`. Consider using `Effect.fail(...)` with a `DesktopWorkspaceError` so the invalid-path condition is handled as a normal error.

Also found in 1 other location(s):
- apps/desktop/src/ipc/methods/workspace.ts:60 -- `deleteStudentWorkspace` wraps `workspace.deleteStudentWorkspace(...)` with `Effect.match`, but the implementation in `DesktopWorkspace` uses `Effect.die(...)` when `workspaceFolder` resolves outside the `students` directory. `Effect.match` does not catch defects, so an invalid or malicious `workspaceFolder` makes this handler reject the IPC call instead of returning the declared `{ success: false, error }` result shape.

[macroscopeapp]

🟡 Medium app/DesktopEnvironment.ts:158

workspaceRoot is used directly from config.tutoratlasWorkspace without expanding ~ or resolving to an absolute path. When a user sets TUTORATLAS_WORKSPACE=~/tutoratlas, the value ~/tutoratlas is used as-is, so backendCwd is passed to the backend process as the literal relative path ~/tutoratlas, causing startup to fail with ENOENT. Consider expanding ~ to homeDirectory and resolving to an absolute path before using the value.

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

In file @apps/desktop/src/app/DesktopEnvironment.ts around line 158:

`workspaceRoot` is used directly from `config.tutoratlasWorkspace` without expanding `~` or resolving to an absolute path. When a user sets `TUTORATLAS_WORKSPACE=~/tutoratlas`, the value `~/tutoratlas` is used as-is, so `backendCwd` is passed to the backend process as the literal relative path `~/tutoratlas`, causing startup to fail with `ENOENT`. Consider expanding `~` to `homeDirectory` and resolving to an absolute path before using the value.

[macroscopeapp]

🟡 Medium src/desktopBootstrap.ts:9

Renaming the required field t3Home to tutoratlasHome breaks wire compatibility. Effect Schema.Struct requires listed fields and disallows extra properties, so an older producer that sends { "t3Home": "..." } will be rejected as missing tutoratlasHome — a mixed-version desktop/server pair or stored bootstrap fixture will fail startup. Consider restoring the original field name or adding a compatibility layer (e.g., Schema.propertySignature with Schema.optional for both names, or decoding both and re-encoding under the new name) so older payloads still decode.

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

In file @packages/contracts/src/desktopBootstrap.ts around line 9:

Renaming the required field `t3Home` to `tutoratlasHome` breaks wire compatibility. Effect `Schema.Struct` requires listed fields and disallows extra properties, so an older producer that sends `{ "t3Home": "..." }` will be rejected as missing `tutoratlasHome` — a mixed-version desktop/server pair or stored bootstrap fixture will fail startup. Consider restoring the original field name or adding a compatibility layer (e.g., `Schema.propertySignature` with `Schema.optional` for both names, or decoding both and re-encoding under the new name) so older payloads still decode.

[macroscopeapp]

🟡 Medium pdf/DesktopPdfRenderer.ts:102

Effect.timeout fails with the tag "TimeoutException", but Effect.catchTag at line 102 matches "TimeoutError", so the catch never triggers. When the page load exceeds PDF_TIMEOUT_MS, the raw TimeoutException escapes instead of being converted to DesktopPdfRendererError, violating the advertised error type. Use Effect.catchTag("TimeoutException", …) so timeouts are mapped correctly.

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

In file @apps/desktop/src/pdf/DesktopPdfRenderer.ts around line 102:

`Effect.timeout` fails with the tag `"TimeoutException"`, but `Effect.catchTag` at line 102 matches `"TimeoutError"`, so the catch never triggers. When the page load exceeds `PDF_TIMEOUT_MS`, the raw `TimeoutException` escapes instead of being converted to `DesktopPdfRendererError`, violating the advertised error type. Use `Effect.catchTag("TimeoutException", …)` so timeouts are mapped correctly.