Skip to content

docs(roadmap): mdx-content-system phase + GSC-validated content paths - #500

Draft
bntvllnt wants to merge 7 commits into
mainfrom
worktree-guides-ai-ui-pillar
Draft

docs(roadmap): mdx-content-system phase + GSC-validated content paths#500
bntvllnt wants to merge 7 commits into
mainfrom
worktree-guides-ai-ui-pillar

Conversation

@bntvllnt

@bntvllnt bntvllnt commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Related to #469.

  • Adds localized /guides discovery and allowlisted guide routes with canonical, hreflang, and TechArticle metadata.
  • Adds EN/FR MDX guides, sitemap entries, and route/content-safety coverage.
  • Merges current origin/main at 903cff3 (including the native renderer foundation and deprecated ntk removal) while preserving the draft guide scope and canary-only release policy.

Validation at 956f0e9

  • pnpm install --frozen-lockfile
  • pnpm -F @vllnt/ui-registry i18n:check
  • pnpm -F @vllnt/ui-registry exec vitest run lib/content-routes.test.ts — 8 passed
  • pnpm -F @vllnt/ui-registry exec eslint 'app/[locale]/guides/[slug]/page.tsx' 'app/[locale]/guides/page.tsx' app/sitemap.ts lib/content-routes.ts lib/content-routes.test.ts
  • pnpm -F @vllnt/ui-registry exec playwright test e2e/guides.spec.ts — 4 passed
  • git diff --check origin/main...HEAD

Fresh GitHub Actions CI was triggered by the push of 956f0e9. This PR remains a draft; no merge or release action was taken.

@bntvllnt
docs(roadmap): record GSC-validated SEO paths + component gaps
ab64099 
90d GSC analysis (sc-domain:ui.vllnt.ai/.com) of real search demand:

- seo-content-engine: SYNC note with the highest-impact CAPTURE paths
  the data proves and that don't exist yet (/alternatives/radix,
  /alternatives/mui, a /react/{component} framework-qualified
  namespace), plus the honest finding that "AI UI development" has
  zero head-term demand today — a recall/GEO bet, not a capture play.
- Later: multiselect + filter-bar component gaps (GSC demand exists,
  no component in the registry today).

Planning/analysis only — no page built (per direction).
@vllnt-pilot
vllnt-pilot Bot deployed to Preview · pr-500 (ntk) July 13, 2026 12:23 Active
@vllnt-pilot

vllnt-pilot Bot commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown

ntk preview

App Status Preview
ui-registry Failed: build ui-registry: build failed: exit status 1 —
storybook Skipped (preview cell not configured) —

Built from b7399c31 · public + no-index (ADR-082) · torn down on close

@bntvllnt
docs(roadmap): add mdx-content-system phase + GSC-validated content p…
04312ea 
…aths

Adds the full MDX-max plan and the GSC-validated SEO paths as roadmap
work, per the roadmap convention.

New phase `mdx-content-system` [PLANNED] (7 tasks, sequenced before
seo-content-engine):
- Shared MDX component map, extended frontmatter schema (JSON-LD from
  frontmatter), generic /guides|/vs|/react [slug] shells, sitemap via
  content glob, an author guard for the MDX evaluate() bracket hazard,
  and migration of the 3 shipped TSX /vs pages onto the MDX shell.
- Outcome: a new content page = one .mdx file drop (no TSX, no sitemap
  edit), i18n-ready via fr.mdx with zero code change.

seo-content-engine: +7 tasks (.9-.15) for the GSC-proven paths —
/vs/radix, /vs/mui, /react/{callout,floating-action-button,code-block},
/guides/ai-ui pillar (+ mobile coming-soon), /guides/streaming-ui +
/guides/design-tokens, and the assistant-ui namespace migration.

Namespace decisions recorded: /vs = tools+libs, /alternatives =
direct competitors, /integrations = how-to-use, /guides = evergreen
reference, /blog = dated articles.
@vllnt-pilot
vllnt-pilot Bot deployed to Preview · pr-500 (ntk) July 17, 2026 14:03 Active
@bntvllnt bntvllnt changed the title docs(roadmap): GSC-validated SEO paths + component gaps docs(roadmap): mdx-content-system phase + GSC-validated content paths Jul 17, 2026
@bntvllnt bntvllnt self-assigned this Jul 29, 2026
@bntvllnt

bntvllnt commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator Author

Review disposition: keep draft, bounded rework before ready

Verdict: do not close as stale/superseded. The roadmap direction still fits the current vllnt/ui priorities: issue #469 is still open as the SEO/GEO visibility-track tracker, the current ROADMAP already carries that track, and the PR's mdx-content-system phase is a sensible prerequisite for the planned content-engine paths. Keep this PR as the roadmap update, but it should remain draft until the metadata and stale references below are fixed.

Blocking before ready:

  1. Link the PR to the tracker issue. Live PR metadata still has closingIssuesReferences: [], and the latest Enforce issue-linked PRs check is failing. Add Related to #469 if this PR is just updating the roadmap under the umbrella, or create/link a narrower issue if you want this PR to close a specific task. Remove the placeholder note that says to add a link later.

  2. Refresh the PR body and checks at the current head. The body still says Issue-link CI gate: add Closes #N before merge (kept draft), and the green non-link checks are from July. After the issue link/body update, rerun or push a no-op body-only metadata refresh so the PR shows fresh status before gh pr ready.

  3. Normalize the new verification URLs to the live domain. The added roadmap tasks use https://ui.vllnt.com/... for new content-path checks at ROADMAP.md:261, 263, and 275-287. Current repo context and live site direction are ui.vllnt.ai; keep .com only where the task is explicitly validating stale-domain redirects, otherwise use .ai for future content/sitemap verification commands.

  4. Reconcile the roadmap tracker with the inserted phase. Issue Roadmap: SEO/GEO visibility track (rank for humans + AI agents) #469 currently lists the SEO/GEO track as search-consolidation -> ai-toolchain-registration -> visibility-measurement -> seo-content-engine -> backlink-authority; this PR inserts mdx-content-system between measurement and content. Update the issue body or add a child issue so the canonical tracker and ROADMAP do not disagree.

  5. Either make the new spec refs real or replace them with issue refs. This PR adds docs/specs/mdx-content-system.md and docs/specs/ai-ui-pillar.md references, but docs/specs/ does not exist on this branch. Existing roadmap drift may predate the PR, but newly added dangling refs should not be introduced without a clear follow-up owner.

Verified clean:

  • Diff scope is bounded: one file, ROADMAP.md only (+30/-3).
  • The phase/task structure follows the existing roadmap convention: kebab-case phase slug, stable task IDs, explicit validate/E2E tasks, and preserved history.
  • The implementation premise is plausible from the current tree: MDXContent, enableMDX, removeImportStatements, getPageContent, pageFrontmatterSchema, and lib/jsonld.ts all exist.

Validation evidence:

No merge/release action taken. This is a draft-disposition comment, not an approval.

@bntvllnt bntvllnt mentioned this pull request Sep 7, 2026
Open
12 tasks
@bntvllnt bntvllnt mentioned this pull request Sep 8, 2026
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@bntvllnt bntvllnt

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bntvllnt