docs: expand registry documentation pages

[bntvllnt]

Summary

• Add routed documentation pages for installation, CLI, theming, registry, components, agents, contributing, changelog, and FAQ.
• List the docs pages in the /docs index, sidebar, sitemap, llms.txt, and llms-full.txt.
• Add per-page metadata plus TechArticle and breadcrumb structured data.
• Clarify the installation styling contract: package installs import @vllnt/ui/styles.css, use @vllnt/ui/tailwind-preset, and scan app source paths; registry installs keep copied component paths in Tailwind scanning; @vllnt/ui/themes/default.css is variables-only and not a full stylesheet substitute.

Validation

• pnpm -F @vllnt/ui lint
• pnpm -F @vllnt/ui exec tsc --noEmit --project tsconfig.build.json
• pnpm -F @vllnt/ui-registry exec tsc --noEmit --project tsconfig.json
• pnpm build
• pnpm test:once
• git diff --check

Notes: pnpm build still emits the existing Next.js multiple-lockfile worktree warning. pnpm test:once still emits existing jsdom navigation, ShareDialog description, and InteractiveTimeline duplicate-key warnings while passing all tests.

Closes #248

[bntvllnt]

Review — 1 finding (1 blocking)

BLOCKING

• C1 — Installation docs do not include the actual VLLNT UI styling contract.
  • Evidence: apps/registry/content/pages/docs/installation.mdx:52-56; packages/ui/package.json:34-39; packages/ui/styles.css:1-64; README.md:50-59.
  • Why it matters: the new public install page tells users to import @vllnt/ui, render <Button />, and then says the minimum Tailwind setup is only @import "tailwindcss";. That does not import the exported VLLNT CSS variables/styles, and it omits the @vllnt/ui/tailwind-preset path documented elsewhere. A user following this page can end up with unresolved/missing semantic utility output or unstyled components, especially because the package peer contract is Tailwind >=3.0.0 while the snippet is Tailwind-v4-shaped.
  • Fix: make the install page split package-vs-registry setup and include the actual required package setup: import @vllnt/ui/styles.css (and theme CSS if required) plus the @vllnt/ui/tailwind-preset/content-scanning guidance for Tailwind 3, or explicitly state that the shown @import "tailwindcss"; snippet is only for Tailwind v4 hosts and provide the v3 equivalent.

WARN

• The new FAQ answer for "What are the peer dependencies?" lists Radix primitives as peer/runtime expectations, but packages/ui/package.json keeps Radix packages under regular dependencies; tighten that wording while fixing C1 so consumers do not install unnecessary peers.

VERIFIED CLEAN

• Reviewed all 19 changed files: docs dynamic route, docs index, DOCS_PAGES, header/sidebar indexing, sitemap, llms.txt, llms-full.txt, JSON-LD helpers, and all new MDX docs pages.
• /docs/[slug] statically generates all 9 docs pages from the shared DOCS_PAGES source.
• /docs, sidebar, sitemap, llms.txt, and llms-full.txt all consume the shared docs registry and include the new docs pages.
• Build output confirmed /docs/[slug] SSG paths and generated llms.txt, llms-full.txt, and sitemap.xml include every new docs slug.
• /mcp exists, so the agents-page MCP mention is not a missing-route claim.
• JSON-LD scripts use escaped JSON via jsonLdScriptAttributes; breadcrumb and TechArticle additions are structurally safe.

VALIDATION

• GitHub checks: all passing for PR docs: expand registry documentation pages #342 at 513bb48dc2761163989af9103f7de85665554027.
• Local: git diff --check origin/main...HEAD passed.
• Local: pnpm -F @vllnt/ui-registry exec tsc --noEmit --project tsconfig.json passed.
• Local: pnpm -F @vllnt/ui-registry build passed and generated static docs/llms/sitemap outputs.
• Local static smoke verified all docs slugs exist and docs/sitemap/llms/sidebar routes share DOCS_PAGES.
• Validation gap: local pnpm -F @vllnt/ui-registry lint failed in the detached worktree because the symlinked install resolved ESLint/plugin internals through a different worktree and crashed on untouched apps/registry/app/report/report-bug-form.tsx; I did not treat that as PR-specific evidence. GitHub Quality Gates are green.

Authorship note: this PR is authored by the authenticated account, so if GitHub refuses a formal REQUEST_CHANGES review, treat this comment/fallback as the authoritative request-changes-equivalent review for this head.

[bntvllnt]

Inline review comment for PR #342 head 513bb48. Formal REQUEST_CHANGES was rejected by GitHub because the authenticated account owns this PR; see the fallback PR comment for the full request-changes-equivalent review.

[bntvllnt]

Blocking: this installation section does not include the actual VLLNT UI styling contract. A user can follow the package path above (pnpm add @vllnt/ui, import Button) and then only apply @import "tailwindcss";, but the package exports @vllnt/ui/styles.css and @vllnt/ui/tailwind-preset, and existing docs/architecture describe the preset as what maps VLLNT semantic variables to Tailwind tokens. Please split package vs registry setup and show the required CSS/preset/content-scanning guidance (or clearly mark the @import "tailwindcss"; snippet as Tailwind v4-only and include the Tailwind 3 equivalent), otherwise the public install docs can produce unstyled/missing semantic utilities for consumers.

[bntvllnt]

@bntvllnt Review update for PR #342 (head c2128c3): no source-level blocking findings found on this pass.

What I re-checked:

• Reused the existing worktree at /home/ubuntu/ui/.worktrees/issue-248-expanded-docs and confirmed it is at PR head c2128c3db3fd02f22a960c7c11bab0b4d5ab9393.
• Verified the previous docs-accuracy blocker is addressed: apps/registry/content/pages/docs/installation.mdx now documents package installs with @vllnt/ui/styles.css, @vllnt/ui/tailwind-preset, app source scanning, registry copied-component destination scanning, and clarifies that @vllnt/ui/themes/default.css is variables-only.
• Checked the implementation paths for the expanded docs pages, sidebar, sitemap, llms.txt, llms-full.txt, and structured-data helpers.

Validation run locally on this pass:

• git diff --check origin/main...HEAD — pass
• pnpm -F @vllnt/ui-registry exec tsc --noEmit --project tsconfig.json — pass

Existing PR/CI evidence:

• PR body reports pnpm -F @vllnt/ui lint, pnpm -F @vllnt/ui exec tsc --noEmit --project tsconfig.build.json, pnpm -F @vllnt/ui-registry exec tsc --noEmit --project tsconfig.json, pnpm build, pnpm test:once, and git diff --check.
• GitHub checks currently pass for Analyze, CodeQL, Enforce issue-linked PRs, Quality Gates, Scan codebase health, Vercel Preview Comments, and Storybook Vercel.

Remaining merge gate:

• Vercel – ui.vllnt.ai is still failing because the deployment was “Canceled from the Vercel Dashboard”. I do not see a code-review blocker tied to that cancellation, but the PR is not fully green until that deployment check is rerun/passes or explicitly accepted as an external canceled check.

Verdict: code/docs review is clean; merge readiness depends on clearing the canceled Vercel deployment status.

[bntvllnt]

@bntvllnt Review verdict: REQUEST_CHANGES recommended — changelog blocker

Head reviewed: c2128c3db3fd02f22a960c7c11bab0b4d5ab9393

BLOCKING

• The PR adds user-facing public docs pages/routes but does not update packages/ui/CHANGELOG.md under [Unreleased]. docs/agents/PR_PLAYBOOK.md requires a changelog entry for user-facing changes.

WARNING

• The new docs detail route renders a page-level <h1> while each new MDX page also starts with its own # ... heading, producing duplicate top-level headings on detail pages. Not necessarily a functional blocker, but worth cleaning up for page structure/SEO/accessibility.

STATUS

• GitHub Actions/code checks are green and Vercel – storybook is SUCCESS.
• Vercel – ui.vllnt.ai: FAILURE is eligible for the PM stale-Vercel reviewer-triage waiver only; it is not merge/release approval.
• Validation gap: I did not rerun full local workspace gates; this review used the live GitHub status rollup plus changed-file inspection.

[bntvllnt]

Warning: this route-level h1 is followed by MDX pages that also start with # ..., so each docs detail page renders duplicate top-level headings. Consider making one of them non-h1 or removing duplicate MDX headings.

[vllnt-pilot]

Preview ready · pr-342-ui-registry

Service	Status	Preview
ui-registry	Ready	https://pr-342-ui-registry.preview.vllnt.ai

Inspect

• Deployed to vllnt-cluster from 71cb394
• Reply with /clean to destroy this preview now

[bntvllnt]

@bntvllnt Review verdict: REQUEST_CHANGES recommended — changed registry files fail the repo lint rules.

Head reviewed: 71cb394215d07fef78eca23397c7bfc92b92f6ea

BLOCKING

• C1 — The PR-changed registry TypeScript/TSX files do not pass ESLint when targeted directly.

  • Evidence: I linted only the registry files changed by this PR:

    cd /home/ubuntu/ui/.worktrees/pr-342-review-t3f844e72
    python3 - <<'PY' >/tmp/pr342-review/registry-changed-ts-files.txt
    import subprocess
    files = subprocess.check_output(['git', 'diff', '--name-only', 'origin/main...HEAD'], text=True).splitlines()
    for f in files:
        if f.startswith('apps/registry/') and f.endswith(('.ts', '.tsx')):
            print(f[len('apps/registry/'):])
    PY
    cd apps/registry
    xargs -a /tmp/pr342-review/registry-changed-ts-files.txt pnpm exec eslint

    It exits 123 with 114 problems (114 errors, 0 warnings) across the PR-touched files.
  • Representative failures:
    • apps/registry/app/docs/[slug]/page.tsx:30, :42, :64, :93, :95, :101, :137 — Prettier, unicorn/no-await-expression-member, and unicorn/prevent-abbreviations.
    • apps/registry/app/llms.txt/route.ts:43, :47, :77, :105, :111, :123, :125, :128, :129 — max-lines, loop usage, numeric separators, route handler/header object naming/sorting/formatting.
    • apps/registry/app/llms-full.txt/route.ts:56, :77, :95, :119, :121, :125, :126 — same pattern.
    • apps/registry/app/sitemap.ts:12, :18-20, :42, :44-45, :53-54, :61-68 — function length, route naming, object ordering, no-zero-fractions.
    • apps/registry/components/header/header.tsx:63 — Github icon is deprecated by lucide.
    • apps/registry/lib/docs-pages.ts:1, :64, :68 — docs abbreviation filename/API names.
    • apps/registry/lib/jsonld.ts:15, :22-23, :32-37, :49-56, :66-73, :84-90, :101-117, :129 — schema object keys currently trip naming/sorting/array-type rules and need either compliant construction or scoped disables with rationale.
    • apps/registry/lib/sidebar-sections.ts:1, :68 — import sorting and function length.
  • Why it matters: these are not unrelated whole-repo lint failures; this command targeted the PR's changed registry files. The repo guidance treats workspace gates as blocking, and this leaves the new public docs/agent-surface code outside the same quality bar as the rest of the workspace.
  • Fix: run the registry lint/autofix path for the touched files, split oversized helpers, rename docs* APIs or explicitly configure/justify the abbreviation, replace the deprecated GitHub icon, and add narrow rule exceptions only where external protocol keys (@context, @type, __html, HTTP headers, Next route GET) require them.

• C2 — The user-facing docs expansion still has no changelog file update in this PR.

  • Evidence: git diff --name-only origin/main...HEAD -- '*CHANGELOG.md' returns no files, while the PR adds public docs routes/content and updates /docs, sitemap, /llms.txt, /llms-full.txt, sidebar, header search, and structured data.
  • Why it matters: the earlier review already flagged the changelog requirement, and docs/agents/PR_PLAYBOOK.md / repo rules require the PR body and changelog evidence to match user-facing changes before ship.
  • Fix: add the appropriate [Unreleased] changelog entry for the registry/docs/agent-surface work, or explicitly justify why this docs-site change is exempt under the repo's changelog policy.

VERIFIED CLEAN

• The prior installation-docs accuracy blocker is fixed at current head: apps/registry/content/pages/docs/installation.mdx now documents @vllnt/ui/styles.css, @vllnt/ui/tailwind-preset, app-source Tailwind scanning, registry copied-component destination scanning, and clarifies that @vllnt/ui/themes/default.css is variables-only.
• PR is linked to #248 and the current GitHub status rollup is green at head 71cb394215d07fef78eca23397c7bfc92b92f6ea.
• Reviewed the changed registry route/page/helper files and docs content paths listed by git diff --name-only origin/main...HEAD.

VALIDATION

• Ran: git diff --check origin/main...HEAD — passed, exit 0.
• Ran: pnpm -F @vllnt/ui-registry exec tsc --noEmit --project tsconfig.json — passed, exit 0.
• Ran: pnpm -F @vllnt/ui-registry lint — failed before completion on existing/non-PR file apps/registry/app/report/report-bug-form.tsx:73 with TypeError: (0 , _minimatch.default) is not a function in jsx-a11y/label-has-associated-control; treated as a separate tooling/pre-existing caveat, not the PR-specific blocker above.
• Ran changed-file registry ESLint command shown in C1 — failed, exit 123, 114 errors on PR-changed files.
• Not rerun locally in this pass: full pnpm build / pnpm test:once; GitHub checks for the current head report success.