Add support for consumer side customization of the actual astro config

Problem Summary

Consumers cannot customize the Astro configuration from their side. The framework uses a hardcoded astro.config.mjs file within the doc-core package, preventing users from:

• Adding custom Astro integrations
• Modifying Vite configuration for their specific needs
• Changing the deployment adapter (currently hardcoded to Cloudflare)
• Customizing build settings, output options, or other Astro configurations

Current limitation: While users can customize content via pf-docs.config.mjs, they cannot modify the actual Astro config without forking doc-core and requesting npm releases.

Use Cases

Consumers need to customize Astro config for:

1. Deployment targets: Different hosting platforms (AWS, Netlify, Vercel) require different adapters
2. Vite configuration: Custom resolve aliases, plugins, or build optimizations
3. Integrations: Adding sitemap, analytics, or other Astro integrations
4. Performance tuning: Customizing bundle splitting, compression, or caching strategies
5. Environment-specific settings: Different configs for dev/staging/production

Current Architecture

The CLI currently modifies the Astro config via string replacement in setFsRootDir() (cli/setFsRootDir.ts:17-19), which is brittle and doesn't support general user customization.

// cli/cli.ts:138-141
await build({
  root: astroRoot,
  outDir: docsOutputDir,
})

The CLI invokes Astro's programmatic API with the hardcoded astroRoot config location. Consumers have no way to inject or merge their own configuration.

Completion Criteria

The issue is resolved when:

1. User config file supported: Consumers can create an optional Astro config file that gets merged with the base config
2. Configuration merging: User config is properly merged with doc-core's base config
3. Backward compatibility: Existing setups without user config continue to work with default behavior
4. Clear precedence rules: Documentation clearly explains which config values take precedence (user overrides vs. base defaults)
5. Type safety: User config gets proper TypeScript support and validation
6. All CLI commands supported: Config merging works for start, build, preview, and other commands
7. No string manipulation: Replace the brittle string replacement approach in setFsRootDir() with proper config merging

Technical Notes

• Astro 5.4.0+ supports mergeConfig() for configuration merging (docs)
• The CLI already uses Astro's programmatic API (build(), dev(), preview())
• inlineConfig parameter in programmatic API allows config override
• File locations: cli/cli.ts:138-141, cli/setFsRootDir.ts
• Current string replacement hack: cli/setFsRootDir.ts:17-19

Related Links

• Related issue: #95 (Add ability to pass in vite / astro configurations for doc core) - CLOSED
• Jira: PF-3604
• Astro mergeConfig API: https://docs.astro.build/en/reference/modules/astro-config/
• Astro programmatic API: https://docs.astro.build/en/reference/programmatic-reference/

Start with cli/setFsRootDir.ts:17-19 and cli/cli.ts:138-141, then trace how the start, build, preview, and other CLI commands invoke the programmatic API. Define how an optional consumer config is merged with the base config, including precedence and type support; done means existing defaults remain unchanged and all listed commands support the customization without string manipulation.