| name | corp-web-japan-demo-mdx-migration |
| description | Migrate corp-web-contents demo MDX families (use-cases, AIP demos, ACP demos) into corp-web-japan local MDX publication routes with preview lists, canonical detail routes, route-aligned assets, and focused regression tests. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
corp-web-japan demo MDX migration
Use this when the user asks to migrate a ../corp-web-contents/pages/features/demo/<family>/** MDX family into corp-web-japan.
Supported pattern families proven in practice:
use-cases
aip-features
acp-features
Core rules
- Start from latest
origin/main in a fresh git worktree.
- Do not reuse an old branch/worktree for a new migration request.
- Keep existing public root redirect routes like
/demo/aip or /demo/acp unchanged unless the user explicitly asks to replace them.
- Implement preview list routes under
/t/... and canonical detail routes under the final public route family.
- Keep assets route-aligned under
public/<route-family>/<id>/thumbnail.png.
- Add focused source-based tests first; they are fast and reliable in fresh worktrees.
- If repo-root
node_modules already exists, ../../node_modules/.bin/tsc --noEmit is a useful fast check from a worktree.
Family mappings used successfully
use-cases
- source:
../corp-web-contents/pages/features/demo/use-cases/<id>/<slug>/ja/content.mdx
- preview list:
/t/use-cases
- canonical detail:
/use-cases/:id/:slug
- id redirect:
/use-cases/:id
- content root:
src/content/use-cases/*.mdx
- assets:
public/use-cases/<id>/thumbnail.png
- category key:
use-case
- href prefix:
/use-cases
AIP demos
- source:
../corp-web-contents/pages/features/demo/aip-features/<id>/<slug>/ja/content.mdx
- preview list:
/t/demo/aip
- canonical detail:
/demo/aip/:id/:slug
- id redirect:
/demo/aip/:id
- content root:
src/content/demo/aip/*.mdx
- assets:
public/demo/aip/<id>/thumbnail.png
- category key:
aip-demo
- href prefix:
/demo/aip
ACP demos
- source:
../corp-web-contents/pages/features/demo/acp-features/<id>/<slug>/ja/content.mdx
- preview list:
/t/demo/acp
- canonical detail:
/demo/acp/:id/:slug
- id redirect:
/demo/acp/:id
- content root:
src/content/demo/acp/*.mdx
- assets:
public/demo/acp/<id>/thumbnail.png
- category key:
acp-demo
- href prefix:
/demo/acp
Implementation shape
For each new family, add:
src/content/publications/<family>-publication-records.ts
src/lib/publications/get-<family>-publication-post.ts
- preview list page under
src/app/t/.../page.tsx
- canonical detail page under
src/app/.../[id]/[slug]/page.tsx
- id redirect page under
src/app/.../[id]/page.tsx
src/content/.../*.mdx
public/.../<id>/thumbnail.png
- tests for corpus completeness + route architecture
- sitemap entries
PublicationCategory extension in src/lib/publications/types.ts
- href prefix in
src/lib/publications/get-publication-href.ts
Follow the existing event/news/use-case publication pattern:
- records file scans MDX directory, parses YAML frontmatter, exposes list/params/id helpers
- loader reads MDX, renders with
renderPublicationMdx, extracts TOC via extractHeadingsFromMdx, builds related items from relatedIds
- detail route loads by
id, redirects mismatched slug, renders PublicationPostPage
- preview route uses
ResourceListPage, SiteHeader, SiteFooter, and robots: noindex
Frontmatter normalization
Typical source frontmatter fields:
layout
category
title
description
date as YYYY-MM-DD
ogImage
hideOgImage
hideTableOfContents
relatedPosts
Normalize to:
id
slug
title
description
date converted to Japanese format like 2025ๅนด9ๆ23ๆฅ
heroImageSrc pointing at route-aligned thumbnail
relatedIds
Drop source-only fields like:
layout
category
ogImage
hideOgImage
hideTableOfContents
keywords
Important finding:
- Some source families have blank descriptions for every entry. In that case, fill a minimal useful local description instead of preserving empty strings.
Asset migration
- Read
ogImage from source frontmatter.
- Copy the referenced source file from
../corp-web-contents/public/... into the route-aligned target thumbnail path.
- Do not keep migrated MDX pointing at old
public/demo/..., public/tutorial/..., or other legacy asset roots.
MDX component compatibility
Before finalizing, inspect the imported corpus for custom tags.
Practical findings:
- use-cases only needed
Youtube
- AIP demos only needed
Youtube
- ACP demos needed
Youtube, InfoNote, and additionally BlueState + User
If imported MDX uses unsupported components, add the smallest presentational implementation to src/lib/publications/mdx/components.tsx rather than rewriting all content.
Hero-image duplication rule for YouTube-first demo/publication entries
A reusable corpus-specific finding from the local demo/publication migrations:
- when a migrated MDX entry presents a
<Youtube ... /> embed directly in the article body, the detail-page hero image can become visually redundant with the embedded video
- this has been confirmed for:
/use-cases/:id/:slug
/demo/aip/:id/:slug
/demo/acp/:id/:slug
- in those cases, add
hideHeroImageOnDetail: true to the MDX frontmatter
- make sure the family-specific publication frontmatter parser and
get-*-publication-post.ts loader pass this flag through to PublicationPost
PublicationPostPage already respects post.hideHeroImageOnDetail, so the migration/follow-up work only needs the frontmatter + loader wiring and regression coverage
Practical verification rule:
- add/keep a regression that asserts
if source includes <Youtube, source also includes hideHeroImageOnDetail: true
- also prefer the inverse assertion for these families: if
hideHeroImageOnDetail: true is present, the MDX should include <Youtube
Verification commands
Use these first:
node --test tests/<family>-imported-ja-corpus.test.mjs tests/<family>-mdx-routing-and-preview.test.mjs
../../node_modules/.bin/tsc --noEmit
Good tests should verify:
- expected IDs exist locally
heroImageSrc uses the new route-aligned thumbnail path
- legacy asset paths are gone from migrated MDX
- legacy
/features/demo/<family>/... references are gone from migrated MDX
- preview page is noindex and uses the correct list function
- canonical detail page loads by
id and redirects mismatched slugs
- id-only route redirects correctly
PublicationCategory and href prefix include the new family category
- any newly required MDX components are present
Worktree safety note
Do not assume an ad hoc directory is a real git worktree just because its name looks right.
Use git worktree list --porcelain to confirm the actual registered worktree path before writing files.
Prefer repo-local .worktrees/<branch> paths when creating a new worktree in this repo.
Rebase conflict expectations after another demo migration lands
If one demo-family migration PR sits open while another demo-family migration lands on main, rebasing the older PR will usually conflict in additive registry files rather than in the family-specific content files.
Observed high-probability conflict files:
src/lib/publications/types.ts
src/lib/publications/get-publication-href.ts
src/app/sitemap.ts
- sometimes
.agents/skills/README.md if the PR also added a repo-local migration skill
Resolution rule:
- keep both family categories in
PublicationCategory
- keep both route prefixes in
get-publication-href.ts
- keep both sitemap imports and both mapped route arrays in
src/app/sitemap.ts
- in
.agents/skills/README.md, preserve previously landed migration-skill entries and append the new one instead of taking either side wholesale
This is usually an additive merge, not a semantic choice between alternatives.
After resolving, rerun the focused source tests and the lightweight typecheck before force-pushing the rebased PR branch.
Finish
Before push:
git fetch origin --prune
- if needed,
git stash push -u, git rebase origin/main, git stash pop
- if rebase conflicts happen after another demo migration landed, resolve the shared registry files additively as described above
- rerun focused tests
- commit and push
- open PR with a body file describing route family, asset alignment, and verification