From 5b69546ca5bb674c11d2884980e5d6fc122daa4b Mon Sep 17 00:00:00 2001
From: Wayne Sutton <waynesutton@users.noreply.github.com>
Date: Sun, 11 Jan 2026 00:23:04 -0800
Subject: [PATCH] npm package prd added

---
 AGENTS.md                       |   4 +-
 CLAUDE.md                       |   2 +-
 content/pages/home.md           |   2 +-
 prds/npm-package-maintenance.md | 209 ++++++++++++++++++++++++++++++++
 public/llms.txt                 |   4 +-
 public/raw/home-intro.md        |   2 +-
 public/raw/index.md             |   2 +-
 7 files changed, 217 insertions(+), 8 deletions(-)
 create mode 100644 prds/npm-package-maintenance.md

diff --git a/AGENTS.md b/AGENTS.md
index 10948b0..ff14109 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,13 +16,13 @@ Your content is instantly available to browsers, LLMs, and AI agents.. Write mar
 
 ## Current Status
 
-- **Site Name**: markdown 
+- **Site Name**: markdown sync
 - **Site Title**: markdown sync framework
 - **Site URL**: https://yoursite.example.com
 - **Total Posts**: 19
 - **Total Pages**: 4
 - **Latest Post**: 2026-01-10
-- **Last Updated**: 2026-01-10T23:49:21.881Z
+- **Last Updated**: 2026-01-11T08:12:05.341Z
 
 ## Tech stack
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 7d1adef..e3f8145 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,7 +5,7 @@ Project instructions for Claude Code.
 ## Project context
 
 <!-- Auto-updated by sync:discovery -->
-<!-- Site: markdown  | Posts: 19 | Pages: 4 | Updated: 2026-01-10T23:49:21.882Z -->
+<!-- Site: markdown sync | Posts: 19 | Pages: 4 | Updated: 2026-01-11T08:12:05.342Z -->
 
 Markdown sync framework. Write markdown in `content/`, run sync commands, content appears instantly via Convex real-time database. Built for developers and AI agents.
 
diff --git a/content/pages/home.md b/content/pages/home.md
index 0158533..b44858b 100644
--- a/content/pages/home.md
+++ b/content/pages/home.md
@@ -9,7 +9,7 @@ textAlign: "left"
 
 The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
 
-**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
+**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
 
 <!-- This is a comments
 Your content is instantly available to browsers, LLMs, and AI
diff --git a/prds/npm-package-maintenance.md b/prds/npm-package-maintenance.md
new file mode 100644
index 0000000..40c6b43
--- /dev/null
+++ b/prds/npm-package-maintenance.md
@@ -0,0 +1,209 @@
+# NPM Package Maintenance Guide
+
+This document explains how to keep the `create-markdown-sync` npm package updated with the main markdown-sync app.
+
+## Overview
+
+The CLI package lives in `packages/create-markdown-sync/` and clones from `github:waynesutton/markdown-site`. When the main app changes, the CLI may need updates to stay compatible.
+
+## Package Location
+
+```
+packages/
+  create-markdown-sync/
+    package.json          # Version and dependencies
+    tsconfig.json         # TypeScript config
+    src/
+      index.ts           # CLI entry point
+      wizard.ts          # Interactive prompts
+      clone.ts           # Template cloning
+      configure.ts       # Site configuration
+      install.ts         # Dependency installation
+      convex-setup.ts    # Convex setup
+      utils.ts           # Helper utilities
+    dist/                # Built JavaScript (gitignored)
+```
+
+## When to Update the CLI
+
+Update the CLI package when:
+
+1. **New configuration options** - Added to `fork-config.json.example` or `siteConfig.ts`
+2. **New wizard prompts needed** - New features require user input during setup
+3. **Template structure changes** - Files moved, renamed, or removed
+4. **Convex setup changes** - Auth config, environment variables, or setup flow
+5. **Bug fixes** - Issues discovered during user testing
+
+## Commands
+
+### Development
+
+```bash
+cd packages/create-markdown-sync
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Test locally via npm link
+npm link
+npx create-markdown-sync test-project
+```
+
+### Publishing
+
+```bash
+cd packages/create-markdown-sync
+
+# Bump version (choose one)
+npm version patch   # 0.1.0 -> 0.1.1 (bug fixes)
+npm version minor   # 0.1.0 -> 0.2.0 (new features)
+npm version major   # 0.1.0 -> 1.0.0 (breaking changes)
+
+# Publish to npm
+npm publish --access public
+
+# Verify publication
+npm view create-markdown-sync
+```
+
+## Checklist: Before Publishing
+
+1. **Push main app changes to GitHub first**
+   - The CLI clones from `github:waynesutton/markdown-site`
+   - Template fixes must be in the remote repo
+
+2. **Test the full flow**
+   ```bash
+   rm -rf test-project
+   npx create-markdown-sync test-project
+   cd test-project
+   npx convex dev
+   npm run sync
+   npm run dev
+   ```
+
+3. **Verify wizard prompts match fork-config.json.example**
+   - New options should have corresponding prompts
+   - Defaults should match the example file
+
+4. **Update version number**
+   - Use semantic versioning
+   - Update `VERSION` constant in `src/index.ts` if displayed
+
+5. **Build successfully**
+   ```bash
+   npm run build
+   # Should complete with no TypeScript errors
+   ```
+
+## Sync Points
+
+These files in the CLI should stay in sync with the main app:
+
+| CLI File | Syncs With | Purpose |
+|----------|------------|---------|
+| `wizard.ts` | `fork-config.json.example` | All config options have prompts |
+| `configure.ts` | `scripts/configure-fork.ts` | Same transformation logic |
+| `configure.ts` | `siteConfig.ts` | Template fixes for known issues |
+| `convex-setup.ts` | `convex/auth.config.ts` | Auth setup flow |
+| `utils.ts` | Success message links | Docs URLs are current |
+
+## Adding New Configuration Options
+
+When a new option is added to `fork-config.json.example`:
+
+1. **Add prompt to wizard.ts**
+   ```typescript
+   // In the appropriate section
+   const newOption = await prompts({
+     type: 'confirm',
+     name: 'newOption',
+     message: 'Enable new feature?',
+     initial: false,
+   });
+   ```
+
+2. **Add to WizardAnswers type**
+   ```typescript
+   export interface WizardAnswers {
+     // ... existing fields
+     newOption: boolean;
+   }
+   ```
+
+3. **Add to buildForkConfig in configure.ts**
+   ```typescript
+   function buildForkConfig(answers: WizardAnswers) {
+     return {
+       // ... existing fields
+       newOption: answers.newOption,
+     };
+   }
+   ```
+
+4. **Test the flow**
+   ```bash
+   npm run build
+   npm link
+   npx create-markdown-sync test-project
+   ```
+
+## Handling Breaking Changes
+
+When the main app has breaking changes:
+
+1. **Update CLI to handle both old and new**
+   - Check for file existence before modifying
+   - Use try/catch for optional operations
+
+2. **Bump major version if CLI behavior changes**
+   ```bash
+   npm version major
+   ```
+
+3. **Update README with migration notes**
+
+4. **Consider backward compatibility period**
+   - Keep old logic for 1-2 releases
+   - Add deprecation warnings
+
+## Troubleshooting
+
+### "Template cloned but configuration failed"
+
+The template likely has syntax errors or missing files. Check:
+- `siteConfig.ts` for embedded quotes or syntax issues
+- `fork-config.json.example` for valid JSON
+
+### "Convex setup blocked by WorkOS"
+
+The CLI should disable auth by default. Check:
+- `configure.ts` `disableAuthConfig()` function
+- `convex/auth.config.ts` in the template
+
+### "TypeScript build errors"
+
+Usually caused by:
+- Missing type definitions
+- Spread operator ordering (put spread first, then defaults)
+- Import path issues (.js extensions required for ESM)
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 0.1.0 | Initial release with 13-section wizard |
+
+## Resources
+
+- npm package: https://www.npmjs.com/package/create-markdown-sync
+- Template repo: https://github.com/waynesutton/markdown-site
+- Docs: https://www.markdown.fast/docs
+- Deployment: https://www.markdown.fast/docs-deployment
+- WorkOS setup: https://www.markdown.fast/how-to-setup-workos
diff --git a/public/llms.txt b/public/llms.txt
index 663889a..d579b7b 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -1,11 +1,11 @@
 # llms.txt - Information for AI assistants and LLMs
 # Learn more: https://llmstxt.org/
-# Last updated: 2026-01-10T23:49:21.883Z
+# Last updated: 2026-01-11T08:12:05.343Z
 
 > Your content is instantly available to browsers, LLMs, and AI agents.
 
 # Site Information
-- Name: markdown 
+- Name: markdown sync
 - URL: https://yoursite.example.com
 - Description: Your content is instantly available to browsers, LLMs, and AI agents. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
 - Topics: Markdown, Convex, React, TypeScript, Netlify, Open Source, AI, LLM, AEO, GEO
diff --git a/public/raw/home-intro.md b/public/raw/home-intro.md
index 249f5c1..a2a5b9a 100644
--- a/public/raw/home-intro.md
+++ b/public/raw/home-intro.md
@@ -7,7 +7,7 @@ Date: 2026-01-11
 
 The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
 
-**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
+**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
 
 <!-- This is a comments
 Your content is instantly available to browsers, LLMs, and AI
diff --git a/public/raw/index.md b/public/raw/index.md
index 1832f44..1c50b1c 100644
--- a/public/raw/index.md
+++ b/public/raw/index.md
@@ -2,7 +2,7 @@
 
 The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
 
-**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
+**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
 
 <!-- This is a comments
 Your content is instantly available to browsers, LLMs, and AI