refactor(tour): rename walkthrough → tour (brand) + add docs pipeline

Brand: rename the user-facing system name from "walkthrough" to
"tour" for pithiness. Renamed:

- scripts/walkthrough.mts → scripts/tour.mts
- walkthrough.json → tour.json
- pnpm walkthrough:* → pnpm tour:*
- Prose / error messages / CLI help: "walkthrough" → "tour"
- .github/workflows/pages.yml + valtown.yml: paths trigger +
  step names reflect new script/config paths
- tour.json "title": "Socket PackageURL.js Tour"

Not renamed (intentional — meander hardcodes them or external
identifiers we don't want to churn):

- walkthrough/ output directory (meander writes here)
- walkthrough.css, walkthrough-part-N.html (meander emits these)
- walkthrough-drag.js, walkthrough-sw.js, walkthrough-comments.js,
  walkthrough-overrides.css (our shims — keep "walkthrough" prefix
  so they sit alongside the meander CSS they extend, consistent in
  devtools)
- wt-* CSS class prefix (backronym: "walking tour")
- Val Town credentials + val-name identifiers (rotating them
  orphans existing creds)

A note-on-naming table in docs/tour.md spells this out for future
readers so the hybrid makes sense at first glance.

Docs pipeline (new): scripts/tour.mts renders docs/*.md markdown
entries listed in tour.json's new "docs" array into <filename>.html
pages alongside the generated part files. Each doc gets the same
chrome as a part page (favicons, preloads, SW, SRI, CSP) and a
topic-nav pill row. index.html picks up a new Topics section
linking every doc.

- Validator: validateDocFilenames enforces shape [a-z]+, uniqueness
  against every other doc, and non-collision with part filenames —
  all errors follow the ERROR MESSAGES doctrine.
- marked 18.0.0 pinned as devDep (no caret).
- First shipping doc: docs/tour.md — the pipeline walkthrough
  itself. Remaining 7 docs (architecture, builders, converters,
  safety, vers, contributing, release) land in follow-up commits.

Author: jdalton

.claude/skills/content-filename-from-title/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: content-filename-from-title
-description: Turns a prose title into a short, single-word, URL-friendly filename for published content (docs, walkthrough parts, blog slugs, guide pages). Use when adding a new entry to a manifest that exposes public filenames (e.g. walkthrough.json parts, docs/*.md for GH Pages), when renaming an existing one, or when a user asks "what should I name this file?"
+description: Turns a prose title into a short, single-word, URL-friendly filename for published content (docs, tour parts, blog slugs, guide pages). Use when adding a new entry to a manifest that exposes public filenames (e.g. tour.json parts, docs/*.md for GH Pages), when renaming an existing one, or when a user asks "what should I name this file?"
 ---
 
 # content-filename-from-title
 
 <task>
 Produce a single-word, lowercase, ASCII-only filename (no extension,
 no hyphens, no digits) that best represents the content of a titled
-page. The filename goes into a config manifest — `walkthrough.json`
+page. The filename goes into a config manifest — `tour.json`
 part entries, `docs/` frontmatter, or similar — where it becomes the
 public URL segment for that page.
 </task>
@@ -30,14 +30,14 @@ procedure so the output is reproducible.
 
 ## Where it fits in the repo
 
-- `walkthrough.json` — the `parts[].filename` field is the URL segment
+- `tour.json` — the `parts[].filename` field is the URL segment
   the page is published under at `socketdev.github.io/socket-packageurl-js/<filename>.html`.
 - `docs/*.md` — the file stem becomes the URL segment when docs are
   stitched into the GH Pages flow (see `docs/pages-design-system.md`
   for the surrounding design system).
 - Any future blog or guide manifest added to this repo.
 
-A build-time validator in `scripts/walkthrough.mts` enforces the
+A build-time validator in `scripts/tour.mts` enforces the
 **shape** (`[a-z]+`) and **uniqueness**; this skill decides the
 **choice** (which word).
 </context>
@@ -134,9 +134,9 @@ cute), adjust. Internal consistency matters — don't mix
 </instructions>
 
 <examples>
-## Worked examples — the 8 walkthrough parts
+## Worked examples — the 8 tour parts
 
-These are the filenames currently in `walkthrough.json` at the time
+These are the filenames currently in `tour.json` at the time
 this skill was written. Each shows the rule that produced the choice.
 
 <example id="1">
@@ -302,7 +302,7 @@ again.
   validator uses when it rejects a bad filename.
 - `docs/pages-design-system.md` — the surrounding design system for
   pages that use these filenames.
-- `scripts/walkthrough.mts` → `validatePartFilenames()` — the
+- `scripts/tour.mts` → `validatePartFilenames()` — the
   validator implementation that enforces the hard constraints.
-- `walkthrough.json` — the current live manifest applying this skill.
+- `tour.json` — the current live manifest applying this skill.
 </further-reading>

.github/workflows/pages.yml

@@ -1,7 +1,7 @@
-name: 📘 Walkthrough (GH Pages)
+name: 📘 Tour (GH Pages)
 
-# Deploys the walkthrough pilot to https://socketdev.github.io/socket-packageurl-js/
-# Trigger: push to main that touches walkthrough sources (plus manual).
+# Deploys the tour pilot to https://socketdev.github.io/socket-packageurl-js/
+# Trigger: push to main that touches tour sources (plus manual).
 #
 # Uses the SocketDev/socket-registry shared composite action for
 # checkout + Node/pnpm setup + install, so toolchain versions stay in
@@ -11,25 +11,27 @@ name: 📘 Walkthrough (GH Pages)
 #
 # Build model:
 #   1. Shared setup-and-install → checkout w/ submodules, pnpm install.
-#   2. `pnpm walkthrough:build` — the `CI` env var (set by all GitHub
+#   2. `pnpm tour:build` — the `CI` env var (set by all GitHub
 #      Actions runners) makes this auto-select the `prod` preset, which
 #      applies --minify + --base-path=/socket-packageurl-js. Locally the
 #      same script defaults to `dev`. No flag drift between CI and the
 #      npm script.
-#   3. Upload `walkthrough/` as the Pages artifact.
+#   3. Upload `walkthrough/` as the Pages artifact. (Meander hardcodes
+#      the output directory name; we keep it to avoid forking meander.)
 #   4. Deploy via actions/deploy-pages.
 
 on:
   push:
     branches: [main]
     paths:
-      - 'walkthrough.json'
+      - 'tour.json'
       - 'walkthrough-comments.js'
       - 'walkthrough-drag.js'
       - 'walkthrough-overrides.css'
       - 'walkthrough-sw.js'
-      - 'scripts/walkthrough.mts'
+      - 'scripts/tour.mts'
       - 'src/**'
+      - 'docs/**'
       - 'assets/favicon/**'
       - '.github/workflows/pages.yml'
       - 'package.json'
@@ -51,7 +53,7 @@ concurrency:
 
 jobs:
   build:
-    name: Build walkthrough
+    name: Build tour
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -68,8 +70,8 @@ jobs:
       - name: Init meander submodule
         run: git submodule update --init --depth=1 upstream/meander
 
-      - name: Generate walkthrough (auto-prod via CI env)
-        run: pnpm walkthrough:build
+      - name: Generate tour (auto-prod via CI env)
+        run: pnpm tour:build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

.github/workflows/valtown.yml

@@ -1,6 +1,6 @@
 name: 🌐 Deploy (Val Town)
 
-# Deploys the walkthrough comment backend to Val Town when the val
+# Deploys the tour comment backend to Val Town when the val
 # source changes on main. Also runnable manually via workflow_dispatch.
 #
 # One-time setup required in the repo settings:
@@ -24,7 +24,7 @@ name: 🌐 Deploy (Val Town)
 # What ships
 # ──────────
 # Every `val/*.ts` file that isn't a `*.test.ts`. The deploy step auto-
-# discovers them via `readdirSync(val/)`; `scripts/walkthrough.mts`
+# discovers them via `readdirSync(val/)`; `scripts/tour.mts`
 # uploads each via Val Town's files API. A deploy receipt with content
 # sha256 per file is printed to the run summary.
 
@@ -33,7 +33,7 @@ on:
     branches: [main]
     paths:
       - 'val/**'
-      - 'scripts/walkthrough.mts'
+      - 'scripts/tour.mts'
       - 'scripts/audit-deps.mts'
       - '.github/workflows/valtown.yml'
       - 'package.json'
@@ -79,8 +79,8 @@ jobs:
           checkout-fetch-depth: '1'
 
       - name: Deploy val
-        # `pnpm walkthrough valtown` runs the Socket.dev malware
-        # audit on the val's transitive closure first — a finding
-        # fails fast before any upload. Deploy receipt (file + sha256)
-        # prints to GITHUB_STEP_SUMMARY at the end.
-        run: pnpm walkthrough valtown
+        # `pnpm tour valtown` runs the Socket.dev malware audit on
+        # the val's transitive closure first — a finding fails fast
+        # before any upload. Deploy receipt (file + sha256) prints to
+        # GITHUB_STEP_SUMMARY at the end.
+        run: pnpm tour valtown

CLAUDE.md

@@ -102,10 +102,10 @@ Errors are a UX surface. When validating config or enforcing invariants, every e
 - If two records collide, name both — not just the second one found
 - Suggest, don't auto-correct. An error that silently repairs state hides the bug in the next run
 
-Example — validator on `walkthrough.json`:
+Example — validator on `tour.json`:
 
-- ✗ `Error: invalid walkthrough config`
-- ✓ `walkthrough.json: part 3 ("Parsing & Normalization") is missing "filename". Add a single-word lowercase filename (e.g. "parsing") to this part — one per part is required to route /<slug>/part/3 at publish time.`
+- ✗ `Error: invalid tour config`
+- ✓ `tour.json: part 3 ("Parsing & Normalization") is missing "filename". Add a single-word lowercase filename (e.g. "parsing") to this part — one per part is required to route /<slug>/part/3 at publish time.`
 
 ## ABSOLUTE RULES
 

docs/pages-design-system.md

@@ -1,10 +1,9 @@
 # Pages Design System
 
-A practical guide to styling the walkthrough site we publish at
+A practical guide to styling the tour site we publish at
 `https://socketdev.github.io/socket-packageurl-js/`. Read this before
 touching `walkthrough-overrides.css`, any generated HTML in
-`scripts/walkthrough.mts`, or when building a new UI that lives on that
-site.
+`scripts/tour.mts`, or when building a new UI that lives on that site.
 
 ## Who this is for
 
@@ -253,7 +252,7 @@ Use when the user is reading, comparing, or reviewing.
 5. No card-on-card nesting. A row lives on the page surface, not inside
    a box inside another box.
 
-### Worked example: walkthrough TOC
+### Worked example: tour TOC
 
 Today the TOC renders like this:
 
@@ -515,7 +514,7 @@ overlay has four slots in strict order:
 4. **Fix**: one concrete step to resolve it
 
 The primary button is `Fix` (or the concrete action, e.g. `Open
-walkthrough.json`). The secondary is `Dismiss`.
+tour.json`). The secondary is `Dismiss`.
 
 ## Anti-patterns
 
@@ -587,17 +586,18 @@ A quick map so you know which file to open:
 
 ```
 socket-packageurl-js/
-├── walkthrough.json            ← content: parts, titles, files, filenames
+├── tour.json                   ← content: parts, titles, files, filenames
 ├── walkthrough-overrides.css   ← tokens + component styles (THIS is the style code)
 ├── walkthrough-drag.js         ← runtime behavior (column splitter)
 ├── walkthrough-comments.js     ← runtime behavior (comments panel)
 ├── scripts/
-│   └── walkthrough.mts         ← generator + post-processor (generates HTML)
+│   └── tour.mts                ← generator + post-processor (generates HTML)
 ├── .github/workflows/
 │   └── pages.yml               ← CI: build + deploy to GitHub Pages
 └── docs/
     ├── api.md                  ← library API reference
     ├── types.md                ← TypeScript types reference
+    ├── tour.md                 ← how the build pipeline works
     └── pages-design-system.md  ← you are here
 ```
 
@@ -624,6 +624,6 @@ keeping it honest:
 - [walkthrough-overrides.css](../walkthrough-overrides.css) — the CSS
   tokens this doc references, with inline comments explaining why each
   value was picked.
-- [scripts/walkthrough.mts](../scripts/walkthrough.mts) — the generator
+- [scripts/tour.mts](../scripts/tour.mts) — the generator
   - post-processor; read this if you need to change the generated HTML
     shape (e.g. to add a new class a component needs).