Rework interactive new-player tutorial (real-map walkthrough + MUD intro)

[adhocmedia]

Hi Nils — this is the reworked interactive tutorial we discussed. As agreed, we've taken ownership of the walkthrough content and rebuilt it on top of your data-driven engine from #60. Happy to adjust anything before it goes in.

What changed

• New "What is MUME?" intro chapter — a short, reading-only opener explaining what a MUD and MUME are before the player types anything. It starts and stays at the top so newcomers can read down at their own pace (no command required to advance; a "Begin the tutorial" button moves on).
• Grounded in the real map — the walkthrough now starts in the Common Room of The Foaming Mug and uses MUME's actual Black Hill Village geography, real room descriptions, and per-chapter MMapper-style map screenshots that show where the player is standing as they move.
• Reduced repetition — plainer chapter card titles and story headings; trimmed some of the florid duplicate copy.
• Tutorial-only companion — kept a lent guide character (Irelm) since the real NPCs wouldn't follow the player; combat uses a snake.
• Clean hand-off — the final chapter points the player at the web client + live MMapper.

Notes

• Chapters are renumbered to insert the intro as chapter 1; the rest of your engine (chapters.data.js, TutorialPlayer.vue, frontmatter schema) is reused.
• Map images live under docs/public/assets/images/tutorial-maps/, matching the image convention from fix images and banners #61.
• Rebased onto latest master (including fix images and banners #61); builds clean.

Once CI runs, the PR preview deployment link is the easiest way to click through the whole thing.

🤖 Generated with Claude Code

Summary by Sourcery

Rework the new-player tutorial into a real-map, guided introduction to MUME that takes beginners from basic concepts through their first adventure and live-client handoff.

New Features:

• Add a reading-only “What is MUME?” introduction and rebuild the interactive walkthrough around Black Hill Village’s real map, locations, and tutorial map imagery.
• Guide players through a complete 16-chapter first-hour journey covering account setup, exploration, inventory, survival, social interaction, trading, combat, recovery, training, renting, and transition to the web client.

Enhancements:

• Update tutorial chapter links, command references, numbering, titles, descriptions, and newcomer-facing navigation to match the reworked walkthrough.
• Use a tutorial-only companion and refreshed emulated interactions to provide a consistent guided experience through movement, social play, and combat.

Documentation:

• Refresh newcomer documentation and landing pages to describe and link to the new 16-chapter tutorial.

Chores:

• Add and organize tutorial map assets for the reworked chapters.

[sourcery-ai]

Reviewer's Guide

Reworks the interactive tutorial into a 16-chapter, real-map walkthrough: it now opens with a pinned reading-only MUD/MUME introduction, uses data-driven per-chapter map visuals and grounded Black Hill Village content, simplifies the prose and interactions, and ends with a web-client/MMapper hand-off.

Sequence diagram for the reading-only tutorial introduction

sequenceDiagram
    participant Reader
    participant TutorialPlayer
    participant ChapterData
    Reader->>TutorialPlayer: Open 1-welcome
    TutorialPlayer->>ChapterData: Load chapter frontmatter and content
    ChapterData-->>TutorialPlayer: Intro with no steps
    TutorialPlayer->>TutorialPlayer: renderStepLog()
    TutorialPlayer->>TutorialPlayer: completeChapter(true)
    TutorialPlayer->>TutorialPlayer: scrollTop()
    TutorialPlayer-->>Reader: Show pinned intro and Begin the tutorial button
    Reader->>TutorialPlayer: advanceNext()
    TutorialPlayer-->>Reader: Navigate to chapter 2

Loading

File-Level Changes

Change	Details	Files
Added a reading-only introduction and updated tutorial sequencing and entry point.	Added the “What is MUME?” chapter with no command-driven steps. Renumbered chapters and redirected the tutorial index to the new opener. Updated chapter titles, descriptions, narrative copy, and introductory account/wakeup flow.	docs/play/tutorial/1-welcome.md docs/play/tutorial/1-orientation.md docs/play/tutorial/index.md docs/play/tutorial/2-look-exits.md docs/play/tutorial/3-look-exits.md docs/play/tutorial/4-examining-containers.md docs/play/tutorial/5-safety-wimpy.md docs/play/tutorial/6-vitals-stats.md docs/play/tutorial/7-equipment-wielding.md docs/play/tutorial/8-movement-doors.md docs/play/tutorial/9-npc-communication.md docs/play/tutorial/10-shopping-trading.md docs/play/tutorial/11-combat-stances.md docs/play/tutorial/12-emergency-fleeing.md docs/play/tutorial/13-recovery-rest.md docs/play/tutorial/14-guilds-training.md docs/play/tutorial/15-safe-haven-rent.md docs/play/tutorial/16-journey.md docs/play/tutorial/2-look-exits.md docs/play/tutorial/7-movement-doors.md docs/play/tutorial/8-npc-communication.md
Extended the data-driven tutorial engine to support per-chapter maps and step-free reading chapters.	Loaded map metadata from chapter frontmatter. Rendered chapter map images and location captions in chapter cards. Automatically completed chapters without interactive steps and provided an intro-specific continuation UI. Kept reading-only chapters pinned to the top and removed duplicate initial step rendering.	docs/.vitepress/theme/components/TutorialPlayer.vue docs/play/tutorial/chapters.data.js
Rebuilt the walkthrough around Black Hill Village geography and real-map visual context.	Added MMapper-style map metadata to location-based chapters. Added the tutorial map image assets used by the walkthrough. Changed the companion character to Irelm and replaced combat’s wolf encounter with a snake. Updated the final hand-off to the web client and live MMapper.	docs/play/tutorial/2-orientation.md docs/play/tutorial/3-look-exits.md docs/play/tutorial/4-examining-containers.md docs/play/tutorial/8-movement-doors.md docs/play/tutorial/9-npc-communication.md docs/play/tutorial/10-shopping-trading.md docs/play/tutorial/11-combat-stances.md docs/play/tutorial/12-emergency-fleeing.md docs/play/tutorial/13-recovery-rest.md docs/play/tutorial/14-guilds-training.md docs/play/tutorial/15-safe-haven-rent.md docs/play/tutorial/16-journey.md docs/public/assets/images/tutorial-maps/

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/.vitepress/theme/components/TutorialPlayer.vue" line_range="60-62" />
<code_context>

 const teachList = computed(() => frontmatter.value?.teach || currentChapterObj.value?.teach || [])

+// Optional per-chapter mini-map: { x, y } mark the "you are here" room as a
+// percentage of the map image; { zoom, fx, fy } optionally crop/zoom to focus
+// the village; { arrow } shows a move direction. Driven from chapter frontmatter.
+const chapterMap = computed(() => frontmatter.value?.map || currentChapterObj.value?.map || null)
+
</code_context>
<issue_to_address>
**issue (bug_risk):** The documented `map` options (`x`, `y`, `zoom`, `fx`, `fy`, and `arrow`) are never applied: the template renders only the image and label, while the pin and arrow CSS has no corresponding markup. Any chapter that supplies those fields still displays the full unannotated image without the promised location marker, crop, or direction indicator.

**Triggers:** When a chapter uses any map positioning, zoom, focus, or arrow metadata.

**Suggested fix:** Render the pin and arrow from the metadata and apply the requested crop/zoom styles, or remove the unsupported fields and comments.
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: docs/.vitepress/theme/components/TutorialPlayer.vue:62

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.

[adhocmedia]

🔎 Live preview

Since the org-root repo's PR-preview base path is broken (see below), I deployed this branch to my fork's Pages so you can click through the real thing:

https://whitecouncil-alt.github.io/mume.github.io/play/tutorial/

Verified end-to-end: intro redirect works, maps load, chapter navigation and titles all render correctly.

✅ Merging

Nothing special required — a normal merge to master is all it needs. On merge, deploy.yml rebuilds master with the base from actions/configure-pages (/ for the org-root site), so the tutorial will be live at:

https://docs.mume.org/play/tutorial/

The base-path bug below only affects PR previews, never the production deploy, so the merged result renders correctly regardless.

🐞 Optional: fix PR previews for future PRs

Previews 404 because pr-preview.yml's org-root check is case-sensitive: owner MUME vs repo mume.github.io, so MUME.github.io != mume.github.io and it wrongly prefixes the base with /mume.github.io/ while deploy.yml serves at /pr-N/. One-line fix (.github/workflows/pr-preview.yml):

      - name: Determine Base URL Prefix
        id: base_url
        run: |
          name_lc=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]')
          owner_lc=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
          if [ "$name_lc" = "$owner_lc.github.io" ]; then
            echo "prefix=/" >> $GITHUB_OUTPUT
          else
            echo "prefix=/${{ github.event.repository.name }}/" >> $GITHUB_OUTPUT
          fi
          echo "host=${{ github.repository_owner }}.github.io" >> $GITHUB_OUTPUT

(Since pull_request runs workflows from the base branch, this only takes effect once it's on master.)

Sourcery withdrew this approval because it has stopped reviewing this pull request.

[sourcery-ai]

Sourcery has withdrawn its approval of this pull request. It auto-reviews a pull request 5 times, and this push is past that limit, so the approval no longer reflects code Sourcery has read.

Comment @sourcery-ai review to get a fresh review, which can approve again.

Re-reviews, rate limits and approvals