Set Up @services/plan

Overview

Set up @services/plan in the ions monorepo — a Cloudflare Workers-deployed SSR documentation site (TanStack Start + Fumadocs) that serves the @plan/ directory as a navigable, searchable docs portal at plan.atlas.prata.ma.

Modeled directly after /Users/bianpratama/Code/pra/pilot/@services/plan. The service renders all Markdown files from @plan/ as a Fumadocs site with full-text search, Mermaid diagram support, and dark/light theming via next-themes.

Goals

• Add required catalog entries to root package.json (react, docs, style, type, infra, build additions)
• Create NETWORK.yml at repo root establishing the 15xxx port policy for ions
• Create @plan/meta.json for Fumadocs navigation ordering
• Scaffold @services/plan/ with all config files (package.json, tsconfig, vite, wrangler, etc.)
• Implement all src/ source files (routes, components, lib)
• Update AGENTS.md with plan commit scope and NETWORK.yml policy
• Run bun install and verify the workspace resolves cleanly
• Verify type-check passes with bun run test:type --filter @services/plan

Non-Goals

• Deploying to Cloudflare (wrangler deploy) — config is set up but deploy is manual
• Setting up Cloudflare account/DNS
• Implementing @services/dashboard or any other service
• Adding content to @plan/ beyond meta.json
• CI/CD pipeline setup

Phases

• Phase 1: Foundation — root package.json catalogs, NETWORK.yml, @plan/meta.json (partially done)
• Phase 2: Service config — all @services/plan config files (partially done)
• Phase 3: Source files — all src/ files (routes, components, lib)
• Phase 4: Integration — bun install, AGENTS.md update, type-check verification

Success

• Root package.json has all new catalog entries (react, docs, style, type, infra, build additions, next-themes)
• NETWORK.yml created with prefix: 15, plan service at port 15001
• @plan/meta.json created with correct nav ordering
• @services/plan/ has all config files (package.json, tsconfig, vite, app.config, wrangler, eslint, .gitignore, source.config)
• All src/ files created: router.tsx, routeTree.gen.ts, __root.tsx, index.tsx, docs/index.tsx, docs/$.tsx, api/search.ts, lib/source.ts, lib/layout.shared.tsx, components/mermaid.tsx, styles.css
• AGENTS.md updated with plan scope and NETWORK.yml policy
• bun install completes without errors
• bun run test:type --filter @services/plan passes

Requirements

• Reference implementation at /Users/bianpratama/Code/pra/pilot/@services/plan
• @repo/typescript/tanstack preset (noEmit, react-jsx, bundler resolution)
• @repo/lint ESLint base config
• Bun workspaces already configured for @services/** in root package.json
• Turbo pipeline already handles build, lint, test:type
• @plan/ directory exists with: architecture.md, model.md, analytics.md, glossary.md, registry.md, domains/, discussions/, plans/

Context

Why This Approach

• Direct port of @pilot/plan — same tech stack (TanStack Start + Fumadocs + Cloudflare Workers), adapted for ions branding and content
• TanStack Start for consistency with planned @services/dashboard
• Fumadocs for its TanStack Start integration and built-in search/theming
• Cloudflare Workers for zero-cold-start global edge deployment
• Content in @plan/ read at build time — fully static at runtime, no DB needed

Key Constraints

• Bun catalog syntax: must add named catalogs to root package.json before referencing with catalog:react, catalog:docs, etc.
• fumadocs-mdx:collections/* is a virtual module — must be mapped in tsconfig paths to .source/* (generated at build time)
• routeTree.gen.ts is auto-generated by TanStack Router — seed manually for initial type-check; regenerated on vite dev
• Default landing: /docs → /docs/architecture (lowercase, matches architecture.md filename)
• Nav title and <title>: Atlas Plan
• Dev port: 15001 (ions uses 15xxx prefix)
• Worker name: pra-atlas-plan; prod domain: plan.atlas.prata.ma

Edge Cases

• routeTree.gen.ts has @ts-nocheck and eslint-disable — never modify manually; TanStack Router regenerates on dev start
• LSP errors in config files before bun install are expected — not real errors
• source.config.ts globs match actual @plan/ structure: *.md, domains/**/*.md, discussions/**/*.md, plans/**/*.md
• Virtual imports fumadocs-mdx:collections/browser and fumadocs-mdx:collections/server resolve via Vite plugin at runtime

Tradeoffs

• Seeding routeTree.gen.ts manually: needed for tsc --noEmit before first vite dev. File is @ts-nocheck so type errors inside are suppressed.
• Catalog version ranges use ^: allows minor/patch upgrades via bun upg while keeping major versions locked
• source.config.ts globs only known subdirs: intentional — avoids pulling in unrelated markdown files

Skills

• plan — plan file format and conventions (this skill)

Boundaries

• Always: Follow the exact file structure from the reference implementation
• Always: Use catalog: references in package.json, never pin versions directly
• Always: Use workspace:* for @repo/lint and @repo/typescript
• Always: Update Progress.md after each task completion
• Ask first: Any structural deviation from the reference
• Ask first: Adding dependencies not in the reference
• Never: Run wrangler deploy — out of scope
• Never: Modify routeTree.gen.ts beyond the initial seed
• Never: Add content to @plan/ markdown files

Questions

• Deploy to Cloudflare? → Config set up; actual deploy is out of scope
• Dark/light theming? → Keep next-themes (match reference)
• Content source path? → ../../@plan
• Create meta.json? → Yes: architecture → model → analytics → glossary → registry → domains → discussions → plans
• Catalog strategy? → Add all needed catalogs to root package.json
• Domains? → prod: plan.atlas.prata.ma, dev: dev.plan.atlas.prata.ma, local: plan.atlas.test
• Default landing? → /docs/architecture
• Site title? → Atlas Plan
• Port? → 15001 (15xxx prefix for ions)
• NETWORK.yml? → Create at repo root