Add @arkenv/fumadocs-ui

.changeset/old-birds-listen.md

@@ -0,0 +1,7 @@
+---
+"@arkenv/fumadocs-ui": patch
+---
+
+#### First release
+
+`@arkenv/fumadocs-ui` provides a theme, and components, for `fumadocs-ui` to replicate the "ArkEnv" website look.

.claude/commands/openspec/apply.md

@@ -0,0 +1,23 @@
+---
+name: OpenSpec: Apply
+description: Implement an approved OpenSpec change and keep tasks in sync.
+category: OpenSpec
+tags: [openspec, apply]
+---
+<!-- OPENSPEC:START -->
+## Guardrails
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+## Steps
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+## Reference
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

.claude/commands/openspec/archive.md

@@ -0,0 +1,27 @@
+---
+name: OpenSpec: Archive
+description: Archive a deployed OpenSpec change and update specs.
+category: OpenSpec
+tags: [openspec, archive]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

.claude/commands/openspec/proposal.md

@@ -0,0 +1,28 @@
+---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

CLAUDE.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

apps/www/app/(home)/page.tsx

@@ -1,3 +1,4 @@
+import { ExternalLink } from "@arkenv/fumadocs-ui/components";
 import type { Metadata } from "next";
 import Image from "next/image";
 import { AnnouncementBadge } from "~/components/announcement-badge";
@@ -9,7 +10,6 @@ import {
 	StarUsButton,
 	VideoDemo,
 } from "~/components/page";
-import { ExternalLink } from "~/components/ui/external-link";
 
 export const metadata: Metadata = {
 	title: "ArkEnv",

apps/www/app/docs/[[...slug]]/page.tsx

@@ -1,3 +1,4 @@
+import { AIActions } from "@arkenv/fumadocs-ui/components";
 import { createRelativeLink } from "fumadocs-ui/mdx";
 import {
 	DocsBody,
@@ -6,7 +7,6 @@ import {
 	DocsTitle,
 } from "fumadocs-ui/page";
 import { notFound } from "next/navigation";
-import { LLMCopyButton, ViewOptions } from "~/components/page-actions";
 import { source } from "~/lib/source";
 import { getLinkTitleAndHref } from "~/lib/utils";
 import { getMDXComponents } from "~/mdx-components";
@@ -26,8 +26,7 @@ export default async function Page(props: {
 				<DocsTitle className="mb-4">{page.data.title}</DocsTitle>
 				<DocsDescription>{page.data.description}</DocsDescription>
 				<div className="flex flex-row gap-2 items-center border-b pt-2 pb-6 mb-8 mt-4">
-					<LLMCopyButton markdownUrl={`${page.url}.mdx`} />
-					<ViewOptions
+					<AIActions
 						markdownUrl={`${page.url}.mdx`}
 						githubUrl={
 							getLinkTitleAndHref(

apps/www/app/globals.css

@@ -1,4 +1,5 @@
 @import "tailwindcss";
+@import "@arkenv/fumadocs-ui/css/theme.css";
 @import "fumadocs-ui/css/ocean.css";
 @import "fumadocs-ui/css/preset.css";
 @import "./styles/theme/light.css";
@@ -11,133 +12,7 @@
 
 @plugin "tailwindcss-animate";
 @source "../node_modules/fumadocs-ui/dist/**/*.js";
-
-/* External link icon variables */
-@theme {
-	--icon-external: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23374151' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='7 7 17 7 17 17'%3E%3C/polyline%3E%3Cline x1='7' y1='17' x2='17' y2='7'%3E%3C/line%3E%3C/svg%3E");
-	--icon-external-dark: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23d1d5db' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='7 7 17 7 17 17'%3E%3C/polyline%3E%3Cline x1='7' y1='17' x2='17' y2='7'%3E%3C/line%3E%3C/svg%3E");
-}
-
-/* Link underlines in documentation */
-article
-a:not(:has(img)):not(.fd-card):not([data-card]):not([class*="fd-"]):not(
-	[data-no-underline]
-),
-[data-external-link]:not(:has(img)):not(.fd-card):not([data-card]):not(
-		[class*="fd-"]
-	):not([data-no-underline]) {
-	text-decoration: none;
-	border-bottom: 1.5px solid currentColor;
-	padding-bottom: 1px;
-	transition: border-bottom-width 0.1s ease;
-}
-
-article
-	a:not(:has(img)):not(.fd-card):not([data-card]):not([class*="fd-"]):not(
-		[data-no-underline]
-	):hover,
-[data-external-link]:not(:has(img)):not(.fd-card):not([data-card]):not(
-		[class*="fd-"]
-	):not([data-no-underline]):hover {
-	border-bottom-width: 2.5px;
-}
-
-/* External links in documentation */
-article
-a[rel*="noopener"][target="_blank"]:not(.fd-card):not([data-card]):not(
-	[data-no-arrow]
-):not(:has(img)),
-[data-external-link]:not(.fd-card):not([data-card]):not([data-no-arrow]):not(
-		:has(img)
-	) {
-	padding-right: 1.1em;
-	background-image: var(--icon-external);
-	background-repeat: no-repeat;
-	background-size: 0.9em;
-	background-position: center right;
-}
-
-.dark
-	article
-	a[rel*="noopener"][target="_blank"]:not(.fd-card):not([data-card]):not(
-		[data-no-arrow]
-	):not(:has(img)),
-.dark
-	[data-external-link]:not(.fd-card):not([data-card]):not([data-no-arrow]):not(
-		:has(img)
-	) {
-	background-image: var(--icon-external-dark);
-}
-
-/* Sidebar & Nav: Automagic icons next to text for flex containers */
-[data-radix-scroll-area-viewport]
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	),
-#nd-nav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	),
-#nd-subnav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	) {
-	background-image: none !important;
-	padding-right: 0 !important;
-	display: inline-flex;
-	align-items: center;
-	gap: 0 !important;
-}
-
-/* Sidebar specifically needs full flex for better link hit-areas */
-[data-radix-scroll-area-viewport]
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	) {
-	display: flex;
-}
-
-[data-radix-scroll-area-viewport]
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after,
-#nd-nav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after,
-#nd-subnav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after {
-	content: "";
-	width: 0.9em;
-	height: 0.9em;
-	margin-left: 0.1em;
-	background-image: var(--icon-external);
-	background-size: contain;
-	background-repeat: no-repeat;
-	background-position: center;
-	flex-shrink: 0;
-	opacity: 0.5;
-}
-
-.dark
-	[data-radix-scroll-area-viewport]
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after,
-.dark
-	#nd-nav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after,
-.dark
-	#nd-subnav
-	a[target="_blank"]:not([data-no-arrow]):not(:has(img)):not(
-		:has(> svg:only-child)
-	)::after {
-	background-image: var(--icon-external-dark);
-}
+@source "../node_modules/@arkenv/fumadocs-ui/dist/**/*.mjs";
 
 button[data-search-full] {
 	--color-fd-secondary: hsl(0, 0%, 100%);

apps/www/bin/mdx.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require("node:child_process");
+
+// Skip mdx types generation during tests - types aren't needed for running tests
+if (process.env.SKIP_MDX === "true") {
+	process.exit(0);
+}
+
+// Get Node.js major version
+const nodeVersion = process.version;
+const majorVersion = Number.parseInt(nodeVersion.slice(1).split(".")[0], 10);
+
+// Set NODE_OPTIONS based on Node.js version
+if (majorVersion >= 25) {
+	// Node.js 25+ has Web Storage enabled by default, disable it to avoid localStorage conflicts
+	const existingOptions = process.env.NODE_OPTIONS || "";
+	const flag = "--no-webstorage";
+
+	// Only add the flag if it's not already present
+	if (!existingOptions.includes(flag)) {
+		process.env.NODE_OPTIONS = existingOptions
+			? `${existingOptions} ${flag}`
+			: flag;
+	}
+}
+// For Node.js 24 and below, leave existing NODE_OPTIONS unchanged
+
+// Check if pnpm is available
+try {
+	execSync("pnpm --version", { stdio: "ignore" });
+} catch {
+	console.error("Error: pnpm is required but not found in PATH");
+	process.exit(1);
+}
+
+// Spawn fumadocs-mdx with the appropriate NODE_OPTIONS
+// Use shell: true on Windows for command resolution, false on Unix for security
+const child = spawn("pnpm", ["exec", "fumadocs-mdx"], {
+	stdio: "inherit",
+	shell: process.platform === "win32",
+});
+
+// Forward exit code
+child.on("exit", (code) => {
+	process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+	console.error("Failed to start fumadocs-mdx:", error);
+	process.exit(1);
+});

apps/www/bin/postinstall.js

@@ -34,6 +34,16 @@ try {
 	process.exit(1);
 }
 
+// Avoid running when @arkenv/fumadocs-ui is not built yet (e.g. fresh CI install)
+try {
+	require.resolve("@arkenv/fumadocs-ui/dist/utils/index.mjs");
+} catch {
+	console.warn(
+		"Skipping fumadocs-mdx: @arkenv/fumadocs-ui is not built (dist missing).",
+	);
+	process.exit(0);
+}
+
 // Spawn fumadocs-mdx with the appropriate NODE_OPTIONS
 // Use shell: true on Windows for command resolution, false on Unix for security
 const child = spawn("pnpm", ["exec", "fumadocs-mdx"], {

apps/www/components/announcement-badge.tsx

@@ -1,7 +1,7 @@
+import { type ArkenvUrl, isExternalUrl } from "@arkenv/fumadocs-ui/utils";
 import { ArrowRight, ArrowUpRight } from "lucide-react";
 import Link from "next/link";
 import type { PropsWithChildren } from "react";
-import { isExternalUrl, type Url } from "~/lib/utils/url";
 import { NewBadge } from "./ui/new-badge";
 
 export function AnnouncementBadge({
@@ -22,7 +22,7 @@ export function AnnouncementBadge({
 	/**
 	 * The link to navigate to when clicking the badge.
 	 */
-	href: Url;
+	href: ArkenvUrl;
 }>) {
 	return (
 		<Link

apps/www/components/ui/card.tsx

@@ -1,9 +1,9 @@
+import { isExternalUrl } from "@arkenv/fumadocs-ui/utils";
 import {
 	Card as CardComponent,
 	type CardProps,
 } from "fumadocs-ui/components/card";
 import { ArrowUpRight } from "lucide-react";
-import { isExternalUrl } from "~/lib/utils/url";
 
 export function Card({ title, ...props }: CardProps) {
 	const isExternal = isExternalUrl(props.href);