Skip to content

fix(catalog): tag discovery tutorial by interface (mcp, api); split out video section - #68

Merged
aaitor merged 3 commits into
mainfrom
aaitor/discover-catalog-lang-tag
Sep 4, 2026
Merged

fix(catalog): tag discovery tutorial by interface (mcp, api); split out video section#68
aaitor merged 3 commits into
mainfrom
aaitor/discover-catalog-lang-tag

Conversation

@aaitor

@aaitor aaitor commented Sep 4, 2026

Copy link
Copy Markdown
Member

Why this matters

Two small presentation fixes to the "What's in the Catalog?" discovery tutorial (follow-up to #67), from review feedback:

  1. It was tagged ts, implying a TypeScript-only tutorial. Discovery is language-agnostic — every surface (REST catalog, MCP tools, ARD registry, crawler feed) is a plain HTTP/MCP call from any language, shown as curl. It now carries two interface tags, mcp and api, so a Python or Go developer isn't wrongly filtered out.
  2. The guided-tour video and the interactive demo now live in separate sections — §4 See it run is the working, live demo; §5 Catalog video is the walkthrough — so the two aren't conflated in one panel.

What changed

  • lib/types.ts — add an agnostic Language plus a languageTags() helper that maps a language to its chip(s): agnostic → ["mcp","api"], everything else → its single existing label. One source of truth for all render sites.
  • app/t/[slug]/page.tsx — render one chip per tag; add §5 "Catalog video" (discover tutorials only) and drop the video from the demo panel.
  • app/page.tsx (gallery) & components/AppShell.tsx (sidebar) — render tags via the helper. This also fixes the sidebar, which rendered the raw language value (it would have shown agnostic).
  • components/DiscoverPanel.tsx — no longer renders the video (moved to §5).

Additive: ts/py/autonomous tutorials render exactly as before.

Test plan

  • node lib/demo-agent.mjs + node lib/catalog-discovery.mjs — self-checks pass.
  • npm run build — green (type-checks LANGUAGE_LABEL totality and content/tutorials.ts); 17 static pages.
  • Verified live in the local dev server: header shows two chips mcp api; sidebar shows mcp api (no raw agnostic); §4 is the live demo (8 result cards, facet bars fill) with no video; §5 "Catalog video" holds the player; other tutorials unchanged.

Follow-up to #67.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NJVmLG9aiAzymDX4n56duk

aaitor and others added 2 commits September 4, 2026 15:56
The discover-the-catalog tutorial is language-agnostic — every discovery
surface is curl/MCP/REST, callable from any language. Labelling it "ts"
implied a TypeScript-only tutorial. Add an `agnostic` Language that renders
as "mcp + api" (labelled by interface, not language) and use it for the entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NJVmLG9aiAzymDX4n56duk
…ection

Follow-up review feedback on the discovery tutorial:

- Render the language-agnostic tutorial as two separate chips, "mcp" and
  "api", instead of one "mcp + api" chip. A `languageTags()` helper is now the
  single source of truth for language→chip(s) across the tutorial page, the
  overview and the sidebar — which also fixes the sidebar showing the raw
  `agnostic` enum value (it rendered `it.language` directly, not the label).
- Split the discover "See it run" (§4, the working demo) from the video, which
  now has its own §5 "Catalog video". The video no longer sits inside the demo
  panel.

Build green; both self-checks pass; verified in the local dev server.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NJVmLG9aiAzymDX4n56duk
@aaitor aaitor changed the title fix(catalog): tag discovery tutorial as "mcp + api", not "ts" fix(catalog): tag discovery tutorial by interface (mcp, api); split out video section Sep 4, 2026
@r-marques

Copy link
Copy Markdown
Member

👀 Reviewing

@r-marques r-marques left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated PR review — 🟡 Mergeable with nits

Retags the catalog-discovery tutorial from ts to a new language-agnostic variant rendered as two interface chips (mcp, api), and lifts the guided-tour video out of DiscoverPanel into its own §5 on the tutorial page. The retag is substantively right and the refactor is clean — languageTags() is a single source of truth with a total fallback, so every render site moves together. Nits only; nothing blocks.

What I reviewed

  • Diff range origin/main...HEAD — 6 files, +58/−23, head 3735f6b0.
  • Panel: none — my own source-level verification of each claim.
  • Checked the retag against the tutorial's own content, not the PR title: tutorials.ts tech.stack is ["REST catalog API", "Catalog MCP", "ARD registry", "/.well-known/ard.json", …] and a learn bullet reads "Query it as an agent over REST, the Catalog MCP (search_services), and the ARD registry". So ts was genuinely wrong — nothing in this tutorial is TypeScript-specific — and mcp + api describes it.
  • Verified the new §5 can't leave a numbering gap: §1–§4 in app/t/[slug]/page.tsx (:73, :89, :126, :167) are all unconditional, and §5 is the only conditional one, so a discover tutorial reads 1-2-3-4-5 and every other tutorial reads 1-2-3-4.
  • Confirmed the video move is behaviour-preserving: discoverVideo is gated on t.run.kind === "discover", which is exactly the set DiscoverPanel used to receive, and the <track> list plus the no-playback fallback text carried over verbatim.
  • Checked for a language filter that would need the new variant added — there is none; Language appears outside lib/types.ts only as an AppShell prop type, so no filter UI goes stale.
  • Checked the sidebar CSS for a width cap that two words could overflow: .sb-item .lang (globals.css:128) sets only margin-left:auto and a font — no fixed width, no truncation — so the longer value is cosmetic, not clipped.

Verdict: 🟡 Mergeable with nits — 0 blockers, 0 should-fix, 3 nits.

🧭 Inline comments (4)

Each is posted on its line in Files changed.

  • 💡 NIT — A "mcp" language chip collides with the existing Protocol value of the same name — showcase/lib/types.ts:152
  • 💡 NIT — Sidebar joins the tags with a bare space, so two tags read as one token — showcase/components/AppShell.tsx:111
  • 💡 NIT — This label can never render — LANGUAGE_TAGS always shadows it for agnostic — showcase/lib/types.ts:145
  • NICE — Narrowing on run.kind keeps the video move behaviour-preserving — showcase/app/t/[slug]/page.tsx:35

Comment thread showcase/lib/types.ts
Comment thread showcase/components/AppShell.tsx Outdated
Comment thread showcase/lib/types.ts Outdated
Comment thread showcase/app/t/[slug]/page.tsx

@r-marques r-marques left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Approved with comments — no blockers; 0 should-fix, 3 nit(s) left inline.

Inline review: #68 (review)

Review nits on #68:
- AppShell: join interface tags with " · " (interpunct, as used elsewhere) so
  the sidebar reads "mcp · api" as two tags, not one token.
- types.ts: LANGUAGE_LABEL.agnostic is unreachable for chips (languageTags reads
  LANGUAGE_TAGS instead); set it to "agnostic" with a comment so nobody edits a
  dead string expecting the chip text to change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NJVmLG9aiAzymDX4n56duk
@aaitor
aaitor merged commit 95a25b6 into main Sep 4, 2026
2 checks passed
@aaitor
aaitor deleted the aaitor/discover-catalog-lang-tag branch September 4, 2026 14:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants