feat(tutor): teach Hunk inside an interactive review

[mikeclarke]

Summary

• add hunk tutor, a safe synthetic multi-file review with six guided lessons
• drive lesson progress from semantic command events and the user's effective keybindings
• teach navigation, horizontal panning, view shaping, filtering, agent rationale, and inline notes
• keep tutorial view changes transient and document the new command

Stack

Depends on #717.

Testing

• bun run typecheck
• bun run lint
• bun run check:docs
• bun test src/app/startup.test.ts src/core/config.test.ts src/ui/AppHost.tutor.test.tsx src/tutor/content.test.ts test/pty/tutor.test.ts

hunk-tutor.mp4

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Aug 12, 2026 9:04pm

[greptile-apps]

Greptile Summary

The PR adds a bundled hunk tutor command that loads a synthetic multi-file review and advances lessons from extension events and effective keybindings.

• Adds CLI/config/startup support and a dedicated transient tutor theme.
• Implements the tutor pane, lesson progress, synthetic content, annotations, and command tracking.
• Extends session, watch, workspace, documentation, and test coverage for the new input kind.

Confidence Score: 4/5

The editor lesson should be fixed before merging because it can open a real working-directory file whose path collides with a synthetic tutor lesson.

The tutor otherwise follows the existing startup and extension pipelines, but its editor exercise dispatches the normal host command before adding its explanatory notification, so a matching real path escapes the synthetic-review boundary.

Files Needing Attention: src/extensions/default/ui/tutor/index.tsx

Important Files Changed

Filename	Overview
src/extensions/default/ui/tutor/index.tsx	Implements the tutor extension and lesson state, but the editor lesson can invoke normal file-opening behavior on a coincidentally matching repository path.
src/tutor/content.ts	Defines deterministic synthetic lesson documents and generates the ordered tutorial patch.
src/app/startup.ts	Lazily installs the bundled UI extension only after the tutor command selects the interactive startup path.
src/core/cli.ts	Adds parsing and generated reference metadata for the tutor command.
src/core/config.ts	Adds tutor-specific config layering and defaults the command to its bundled theme.
src/core/loaders.ts	Normalizes the synthetic patch into an ordinary changeset with source fetchers for context expansion.
src/session/app/reloadBounds.ts	Explicitly treats tutor sessions as rootless, causing remote reload attempts to remain rejected before loading.
src/ui/AppHost.tutor.test.tsx	Covers live keybinding rendering, transient view preferences, and horizontal-panning behavior.

Sequence Diagram

sequenceDiagram
  participant U as User
  participant CLI as CLI/config
  participant S as Startup
  participant T as Tutor extension
  participant A as AppHost
  U->>CLI: hunk tutor
  CLI->>S: Tutor input + effective preferences
  S->>T: Install bundled tutor
  S->>A: Synthetic changeset + extension registry
  A->>T: changeset_loaded / startup events
  T-->>U: Guide pane and current keybinding
  U->>A: Execute review command
  A->>T: command_executed event
  T-->>U: Advance lesson progress

Loading

Prompt To Fix All With AI

### Issue 1
src/extensions/default/ui/tutor/index.tsx:130
**Synthetic editor path escapes tutorial**

If the working directory contains a real file whose relative path matches the selected synthetic lesson, this task invokes the normal `hunk.review.editSelectedFile` command before showing the tutor notification, causing `$EDITOR` to open unrelated project content from a tutorial documented as self-contained.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(tutor): teach Hunk inside an intera..." | Re-trigger Greptile}

[greptile-apps]

Synthetic editor path escapes tutorial

If the working directory contains a real file whose relative path matches the selected synthetic lesson, this task invokes the normal hunk.review.editSelectedFile command before showing the tutor notification, causing $EDITOR to open unrelated project content from a tutorial documented as self-contained.

Knowledge Base Used: Extension System: API, Loading, and Host Integration

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/extensions/default/ui/tutor/index.tsx
Line: 130

Comment:
**Synthetic editor path escapes tutorial**

If the working directory contains a real file whose relative path matches the selected synthetic lesson, this task invokes the normal `hunk.review.editSelectedFile` command before showing the tutor notification, causing `$EDITOR` to open unrelated project content from a tutorial documented as self-contained.

**Knowledge Base Used:** [Extension System: API, Loading, and Host Integration](https://app.greptile.com/modem/-/custom-context/knowledge-base/modem-dev/hunk/-/docs/extension-system.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.