client-handover 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sabrkei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+<div align="center">
+  <img src="images/claude-client-handover.png" width="120" alt="claude-client-handover" />
+  <h1>claude-client-handover</h1>
+  <p><em>Scott AK (sabrkei)</em></p>
+</div>
+
+AI-powered handover document generator for frontend developers handing off websites to clients.
+
+Run one command. Get a professional handover document in Markdown, plain text, and HTML — written for both your client and the next developer.
+
+Uses the [Claude API](https://console.anthropic.com) (Anthropic) under the hood.
+
+---
+
+## Install
+
+```bash
+npm install -g client-handover
+```
+
+### API key setup
+
+**If you have Claude Code installed**, no setup needed — `client-handover` will automatically use your existing Claude credentials.
+
+**Otherwise**, set your Anthropic API key as an environment variable:
+
+```bash
+# macOS / Linux
+export ANTHROPIC_API_KEY=your_key_here
+
+# Windows (Command Prompt)
+set ANTHROPIC_API_KEY=your_key_here
+
+# Windows (PowerShell)
+$env:ANTHROPIC_API_KEY="your_key_here"
+```
+
+Get a free API key at [console.anthropic.com](https://console.anthropic.com)
+
+---
+
+## Quick start
+
+```bash
+handover handover
+```
+
+This generates a full handover document with placeholder content in an `output/` folder in your current directory.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `all` | Every section as separate files in one folder |
+| `handover` | Full handover document (all sections combined) |
+| `setup` | Project setup & dependencies |
+| `deploy` | Deployment & hosting info |
+| `credentials` | Logins & API keys template |
+| `license` | Licensing & attribution |
+
+---
+
+## Usage
+
+### With your own project notes
+
+Create a plain text file describing your project:
+
+```
+project-info.txt
+----------------
+Project: Acme Corp website
+Stack: Vue 3, Vite, Netlify
+Repo: https://github.com/you/acme
+Live URL: https://acmecorp.com
+Hosting: Netlify (free tier)
+Domain: Namecheap, auto-renews Jan 2026
+CMS: Netlify CMS
+Analytics: Google Analytics 4
+APIs: Mailchimp (newsletter), Stripe (payments)
+```
+
+Then run any command with that file as input:
+
+```bash
+# Every section as separate files in one folder
+handover all project-info.txt acme-client
+
+# Full combined doc
+handover handover project-info.txt
+
+# Full combined doc with a custom output filename
+handover handover project-info.txt acme-handover
+
+# Individual sections
+handover setup project-info.txt
+handover deploy project-info.txt
+handover credentials project-info.txt
+handover license project-info.txt
+```
+
+The more detail you put in your project-info file, the more accurate and useful the output will be.
+
+---
+
+## Output
+
+All commands generate three files per section inside an `output/` folder.
+
+**Single command** (e.g. `handover`):
+```
+output/
+├── handover.md      ← Paste into Notion, GitHub, or a README
+├── handover.txt     ← Clean plain text for email or printing
+└── handover.html    ← Styled HTML ready to send directly to a client
+```
+
+**`all` command** — every section in its own subfolder:
+```
+output/acme-client/
+├── handover.md / .txt / .html
+├── setup.md / .txt / .html
+├── deploy.md / .txt / .html
+├── credentials.md / .txt / .html
+└── license.md / .txt / .html
+```
+
+| Format | Best for |
+|--------|----------|
+| `.md`  | Notion, GitHub, linear docs |
+| `.txt` | Email attachments, printing |
+| `.html`| Sending directly to a client |
+
+---
+
+## Use as a library
+
+You can also import the prompt builders and doc generator directly into your own project:
+
+```js
+import { handover, setup, generateDoc } from 'client-handover'
+
+// Build a prompt from your project info string
+const prompt = handover('Vue 3 project hosted on Vercel, domain on Cloudflare...')
+
+// Generate and save the document
+await generateDoc(prompt, 'my-client', './docs')
+```
+
+### Available exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `generateDoc(prompt, name, dir)` | async function | Calls Claude API and writes `.md`, `.txt`, `.html` |
+| `handover(projectInfo)` | function | Prompt builder for full handover doc |
+| `setup(projectInfo)` | function | Prompt builder for setup section |
+| `deploy(projectInfo)` | function | Prompt builder for deployment section |
+| `credentials(projectInfo)` | function | Prompt builder for credentials section |
+| `license(projectInfo)` | function | Prompt builder for licensing section |
+
+All prompt builders accept an optional `projectInfo` string. If omitted, Claude generates placeholder content.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- One of the following:
+  - [Claude Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) installed (zero config — credentials detected automatically)
+  - Or an Anthropic API key — [get one free at console.anthropic.com](https://console.anthropic.com)
+
+---
+
+## How it works
+
+1. You provide a plain text description of your project (or nothing, for placeholder output)
+2. The CLI builds a structured prompt for Claude
+3. Claude generates a professional, dual-audience document (plain English for clients, technical detail for developers)
+4. The output is saved as `.md`, `.txt`, and `.html`
+
+Each document section is written for **two audiences**:
+- **The client** — plain English, reassuring tone, no jargon
+- **The next developer** — precise technical detail, commands, file paths
+
+---
+
+## Project structure
+
+```
+client-handover/
+├── cli.js           # CLI entry point
+├── index.js         # Library exports
+├── generator.js     # Claude API call + file output
+├── handover.js      # Full handover prompt builder
+├── setup.js         # Setup section prompt builder
+├── deploy.js        # Deployment section prompt builder
+├── credentials.js   # Credentials section prompt builder
+└── license.js       # Licensing section prompt builder
+```
+
+---
+
+## Changelog
+
+### 1.0.0
+- Initial release
+- Single command: `handover /create`
+- Generates two documents per run — technical handover (for developers) and client handover (plain English)
+- Auto-scans project files: package.json, config files, env variable keys, deploy configs, folder structure, CSS colours
+- First-run setup prompts for API key, name, company, email, and phone
+- Outputs `.md`, `.txt`, and `.docx` formats
+- Auto-detects Claude Code credentials — no API key setup needed if you have Claude Code installed
+
+---
+
+## Contributing
+
+Pull requests are welcome. For major changes, open an issue first.
+
+---
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+import { generateDoc, resolveApiKey, saveApiKey } from './generator.js'
+import { technicalHandoverPrompt, nonTechnicalHandoverPrompt } from './prompts.js'
+import { scanProject } from './scanner.js'
+import chalk from 'chalk'
+import readline from 'readline'
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const { version } = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf-8'))
+
+function normalizeCommand(cmd) {
+  return path.basename(cmd).replace(/^\/+/, '')
+}
+
+function printBanner() {
+  const t = chalk.bold.white
+  console.log()
+  console.log('  ' + t('█   █  ███  █   █ ████   ███  █   █ █████ ████ '))
+  console.log('  ' + t('█   █ █   █ ██  █ █   █ █   █ █   █ █     █   █'))
+  console.log('  ' + t('█████ █████ █ █ █ █   █ █   █ █   █ ████  ████ '))
+  console.log('  ' + t('█   █ █   █ █  ██ █   █ █   █  █ █  █     █ █  '))
+  console.log('  ' + t('█   █ █   █ █   █ ████   ███    █   █████ █  █  '))
+  console.log()
+  console.log(chalk.dim('  Website handover documents for clients & developers') + chalk.dim('  ·  v' + version))
+  console.log()
+}
+
+function printHelp() {
+  printBanner()
+  console.log(chalk.dim('  Usage:'))
+  console.log('    handover /create       Generate technical & non-technical handover documents')
+  console.log('    handover key <key>     Save your Anthropic API key\n')
+  console.log(chalk.dim('  Example:'))
+  console.log('    cd my-client-project')
+  console.log('    handover /create\n')
+}
+
+function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, answer => resolve(answer.trim())))
+}
+
+
+async function runSetup() {
+  const configDir = path.join(os.homedir(), '.handover')
+  const configPath = path.join(configDir, 'config.json')
+
+  let config = {}
+  try {
+    if (fs.existsSync(configPath)) config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+  } catch {}
+
+  const hasApiKey = !!resolveApiKey(config)
+  const hasDeveloperInfo = !!config.developerName
+
+  if (hasApiKey && hasDeveloperInfo) {
+    return {
+      name: config.developerName,
+      company: config.developerCompany || '',
+      email: config.developerEmail || '',
+      phone: config.developerPhone || '',
+    }
+  }
+
+  console.log(chalk.bold('\n──────────────────────────────────────────'))
+  console.log(chalk.bold(' client-handover — first time setup'))
+  console.log(chalk.bold('──────────────────────────────────────────\n'))
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+  if (!hasApiKey) {
+    console.log(' To generate documents you need an Anthropic API key.')
+    console.log(chalk.dim(' Get one free at: https://console.anthropic.com\n'))
+    const key = await ask(rl, ' Enter your Anthropic API key (or press Enter to skip): ')
+    if (key) {
+      config.apiKey = key
+      console.log(chalk.green(' ✓ API key saved.\n'))
+    } else {
+      console.log(chalk.dim(' Skipped. Run "handover key <your-api-key>" at any time.\n'))
+    }
+  }
+
+  if (!hasDeveloperInfo) {
+    console.log(' Your details will appear in all generated handover documents.\n')
+    const name = await ask(rl, ' Your full name: ')
+    if (name) config.developerName = name
+
+    const company = await ask(rl, ' Your company name (press Enter if not applicable): ')
+    if (company) config.developerCompany = company
+
+    const email = await ask(rl, ' Your email address: ')
+    if (email) config.developerEmail = email
+
+    const phone = await ask(rl, ' Your phone number (optional, press Enter to skip): ')
+    if (phone) config.developerPhone = phone
+
+    console.log()
+  }
+
+  rl.close()
+
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8')
+  console.log(chalk.green(' ✓ Setup saved.\n'))
+
+  return {
+    name: config.developerName || '',
+    company: config.developerCompany || '',
+    email: config.developerEmail || '',
+    phone: config.developerPhone || '',
+  }
+}
+
+async function runCreate() {
+  printBanner()
+  const developerInfo = await runSetup()
+
+  console.log(chalk.dim(' Scanning project files...'))
+  const projectInfo = scanProject(process.cwd())
+
+  const techDir = './technical-handover'
+  const clientDir = './handover'
+
+  console.log(chalk.bold('\n Generating Technical Handover Document...'))
+  const techPrompt = technicalHandoverPrompt(projectInfo, developerInfo)
+  await generateDoc(techPrompt, 'technical-handover', techDir)
+
+  console.log(chalk.bold('\n Generating Client Handover Document...'))
+  const nonTechPrompt = nonTechnicalHandoverPrompt(projectInfo, developerInfo)
+  await generateDoc(nonTechPrompt, 'handover', clientDir)
+
+  console.log(chalk.green.bold('\n ✅ Handover documents created successfully!\n'))
+  console.log(`   ${chalk.cyan('./technical-handover/')}`)
+  console.log(`     technical-handover.md`)
+  console.log(`     technical-handover.txt`)
+  console.log(`     technical-handover.docx`)
+  console.log()
+  console.log(`   ${chalk.cyan('./handover/')}`)
+  console.log(`     handover.md`)
+  console.log(`     handover.txt`)
+  console.log(`     handover.docx`)
+  console.log()
+}
+
+async function main() {
+  const [,, rawCommand, secondArg] = process.argv
+
+  if (!rawCommand || rawCommand === '--help' || rawCommand === '-h') {
+    printHelp()
+    process.exit(0)
+  }
+
+  const command = normalizeCommand(rawCommand)
+
+  if (command === 'key') {
+    if (!secondArg) {
+      console.error(chalk.red('\n ❌ Usage: handover key <your-api-key>\n'))
+      process.exit(1)
+    }
+    saveApiKey(secondArg)
+    console.log(chalk.green('\n ✅ API key saved. Run "handover /create" to get started.\n'))
+    process.exit(0)
+  }
+
+  if (command !== 'create') {
+    console.error(chalk.red(`\n ❌ Unknown command: ${rawCommand}\n`))
+    printHelp()
+    process.exit(1)
+  }
+
+  try {
+    await runCreate()
+  } catch (err) {
+    if (err.status === 401) {
+      console.error(chalk.red('\n ❌ Authentication failed. Run "handover key <your-api-key>" to set your API key.\n'))
+    } else {
+      console.error(chalk.red(`\n ❌ Error: ${err.message}\n`))
+    }
+    process.exit(1)
+  }
+}
+
+main()

package/generator.js

@@ -0,0 +1,343 @@
+import Anthropic from '@anthropic-ai/sdk'
+import {
+  Document, Packer, Paragraph, TextRun, HeadingLevel,
+  AlignmentType, BorderStyle, TableRow, TableCell, Table,
+  WidthType, ShadingType
+} from 'docx'
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+export function resolveApiKey(config = null) {
+  if (process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY
+
+  const cfg = config || (() => {
+    try {
+      const p = path.join(os.homedir(), '.handover', 'config.json')
+      if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf-8'))
+    } catch {}
+    return {}
+  })()
+
+  if (cfg?.apiKey) return cfg.apiKey
+
+  const credentialsPath = path.join(os.homedir(), '.claude', '.credentials.json')
+  try {
+    if (fs.existsSync(credentialsPath)) {
+      const creds = JSON.parse(fs.readFileSync(credentialsPath, 'utf-8'))
+      const token = creds?.claudeAiOauth?.accessToken
+      const expiresAt = creds?.claudeAiOauth?.expiresAt
+      if (token && (!expiresAt || expiresAt > Date.now())) return token
+    }
+  } catch {}
+
+  return null
+}
+
+export function saveApiKey(key) {
+  const configDir = path.join(os.homedir(), '.handover')
+  const configPath = path.join(configDir, 'config.json')
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true })
+  let config = {}
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')) } catch {}
+  config.apiKey = key
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8')
+}
+
+const apiKey = resolveApiKey()
+if (!apiKey) {
+  console.error('\n ❌ No API key found. Run "handover key <your-api-key>" or install Claude Code.\n')
+  process.exit(1)
+}
+
+const client = new Anthropic({ apiKey })
+
+// ---------------------------------------------------------------------------
+// Inline text parser — splits a line into TextRun segments handling **bold**,
+// *italic*, `code`, and [link text](url) → just the text
+// ---------------------------------------------------------------------------
+function parseInline(text) {
+  const runs = []
+  // Strip markdown links to plain text
+  text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+
+  const pattern = /(\*\*(.+?)\*\*|\*(.+?)\*|`(.+?)`)/g
+  let lastIndex = 0
+  let match
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      runs.push(new TextRun({ text: text.slice(lastIndex, match.index) }))
+    }
+    if (match[2] !== undefined) {
+      runs.push(new TextRun({ text: match[2], bold: true }))
+    } else if (match[3] !== undefined) {
+      runs.push(new TextRun({ text: match[3], italics: true }))
+    } else if (match[4] !== undefined) {
+      runs.push(new TextRun({
+        text: match[4],
+        font: 'Courier New',
+        size: 18,
+        shading: { type: ShadingType.CLEAR, fill: 'F4F4F4' },
+      }))
+    }
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastIndex < text.length) {
+    runs.push(new TextRun({ text: text.slice(lastIndex) }))
+  }
+
+  return runs.length ? runs : [new TextRun({ text })]
+}
+
+// ---------------------------------------------------------------------------
+// Convert markdown string to an array of docx Paragraph/Table objects
+// ---------------------------------------------------------------------------
+function markdownToDocxChildren(markdown) {
+  const children = []
+  const lines = markdown.split('\n')
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    // Fenced code block
+    if (line.trim().startsWith('```')) {
+      const codeLines = []
+      i++
+      while (i < lines.length && !lines[i].trim().startsWith('```')) {
+        codeLines.push(lines[i])
+        i++
+      }
+      for (const codeLine of codeLines) {
+        children.push(new Paragraph({
+          children: [new TextRun({ text: codeLine || ' ', font: 'Courier New', size: 18 })],
+          shading: { type: ShadingType.CLEAR, fill: 'F4F4F4' },
+          spacing: { before: 0, after: 0 },
+          indent: { left: 360 },
+        }))
+      }
+      // Add small gap after code block
+      children.push(new Paragraph({ text: '' }))
+      i++
+      continue
+    }
+
+    // Horizontal rule
+    if (/^---+$/.test(line.trim())) {
+      children.push(new Paragraph({
+        text: '',
+        border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: 'CCCCCC' } },
+        spacing: { before: 200, after: 200 },
+      }))
+      i++
+      continue
+    }
+
+    // Headings
+    const h1 = line.match(/^# (.+)/)
+    const h2 = line.match(/^## (.+)/)
+    const h3 = line.match(/^### (.+)/)
+    const h4 = line.match(/^#{4,6} (.+)/)
+
+    if (h1) {
+      children.push(new Paragraph({
+        children: parseInline(h1[1]),
+        heading: HeadingLevel.HEADING_1,
+        spacing: { before: 400, after: 160 },
+      }))
+      i++; continue
+    }
+    if (h2) {
+      children.push(new Paragraph({
+        children: parseInline(h2[1]),
+        heading: HeadingLevel.HEADING_2,
+        spacing: { before: 320, after: 120 },
+      }))
+      i++; continue
+    }
+    if (h3) {
+      children.push(new Paragraph({
+        children: parseInline(h3[1]),
+        heading: HeadingLevel.HEADING_3,
+        spacing: { before: 240, after: 80 },
+      }))
+      i++; continue
+    }
+    if (h4) {
+      children.push(new Paragraph({
+        children: [new TextRun({ text: h4[1], bold: true })],
+        spacing: { before: 160, after: 80 },
+      }))
+      i++; continue
+    }
+
+    // Checkbox list items  - [ ] or - [x]
+    const checkbox = line.match(/^(\s*)- \[(x| )\] (.+)/i)
+    if (checkbox) {
+      const checked = checkbox[2].toLowerCase() === 'x'
+      children.push(new Paragraph({
+        children: [
+          new TextRun({ text: checked ? '☑ ' : '☐ ' }),
+          ...parseInline(checkbox[3]),
+        ],
+        indent: { left: 360 },
+        spacing: { before: 40, after: 40 },
+      }))
+      i++; continue
+    }
+
+    // Bullet list items  - or *
+    const bullet = line.match(/^(\s*)[-*+] (.+)/)
+    if (bullet) {
+      const indent = bullet[1].length > 0 ? 720 : 360
+      children.push(new Paragraph({
+        children: [new TextRun({ text: '• ' }), ...parseInline(bullet[2])],
+        indent: { left: indent },
+        spacing: { before: 40, after: 40 },
+      }))
+      i++; continue
+    }
+
+    // Numbered list items
+    const numbered = line.match(/^\d+\. (.+)/)
+    if (numbered) {
+      children.push(new Paragraph({
+        children: parseInline(numbered[1]),
+        numbering: { reference: 'default-numbering', level: 0 },
+        indent: { left: 360 },
+        spacing: { before: 40, after: 40 },
+      }))
+      i++; continue
+    }
+
+    // Bold-only line (often used as a label/key line like **Key:** value)
+    // Handled by parseInline already — fall through to normal paragraph
+
+    // Empty line
+    if (line.trim() === '') {
+      children.push(new Paragraph({ text: '', spacing: { before: 0, after: 80 } }))
+      i++; continue
+    }
+
+    // Normal paragraph
+    children.push(new Paragraph({
+      children: parseInline(line),
+      spacing: { before: 0, after: 80 },
+    }))
+    i++
+  }
+
+  return children
+}
+
+// ---------------------------------------------------------------------------
+// Build a docx Document from markdown
+// ---------------------------------------------------------------------------
+function buildDocx(markdown) {
+  const children = markdownToDocxChildren(markdown)
+
+  return new Document({
+    numbering: {
+      config: [{
+        reference: 'default-numbering',
+        levels: [{
+          level: 0,
+          format: 'decimal',
+          text: '%1.',
+          alignment: AlignmentType.LEFT,
+          style: { paragraph: { indent: { left: 360, hanging: 260 } } },
+        }],
+      }],
+    },
+    styles: {
+      default: {
+        document: {
+          run: { font: 'Calibri', size: 22 },
+          paragraph: { spacing: { line: 276 } },
+        },
+      },
+      paragraphStyles: [
+        {
+          id: 'Heading1',
+          name: 'Heading 1',
+          basedOn: 'Normal',
+          next: 'Normal',
+          run: { bold: true, size: 36, color: '1a1a1a' },
+          paragraph: { spacing: { before: 400, after: 160 } },
+        },
+        {
+          id: 'Heading2',
+          name: 'Heading 2',
+          basedOn: 'Normal',
+          next: 'Normal',
+          run: { bold: true, size: 28, color: '2c2c2c' },
+          paragraph: {
+            spacing: { before: 320, after: 120 },
+            border: { bottom: { style: BorderStyle.SINGLE, size: 4, color: 'E0E0E0' } },
+          },
+        },
+        {
+          id: 'Heading3',
+          name: 'Heading 3',
+          basedOn: 'Normal',
+          next: 'Normal',
+          run: { bold: true, size: 24, color: '444444' },
+          paragraph: { spacing: { before: 240, after: 80 } },
+        },
+      ],
+    },
+    sections: [{ properties: {}, children }],
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+export async function generateDoc(prompt, outputName = 'handover', outputDir = './output') {
+  console.log('⏳ Generating document with Claude...\n')
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 4096,
+    messages: [{ role: 'user', content: prompt }]
+  })
+
+  const markdown = message.content[0].text
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true })
+  }
+
+  const basePath = path.join(outputDir, outputName)
+
+  // Save as Markdown
+  const mdPath = `${basePath}.md`
+  fs.writeFileSync(mdPath, markdown, 'utf-8')
+  console.log(`✅ Markdown saved:   ${mdPath}`)
+
+  // Save as plain text
+  const plainText = markdown
+    .replace(/#{1,6}\s+/g, '')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/`{1,3}[^`]*`{1,3}/g, m => m.replace(/`/g, ''))
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[-*+] /g, '• ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+
+  const txtPath = `${basePath}.txt`
+  fs.writeFileSync(txtPath, plainText, 'utf-8')
+  console.log(`✅ Plain text saved: ${txtPath}`)
+
+  // Save as Word document
+  const doc = buildDocx(markdown)
+  const docxBuffer = await Packer.toBuffer(doc)
+  const docxPath = `${basePath}.docx`
+  fs.writeFileSync(docxPath, docxBuffer)
+  console.log(`✅ Word doc saved:   ${docxPath}`)
+
+  return { markdown, plainText }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "client-handover",
+  "version": "1.2.0",
+  "description": "AI-powered handover document generator for frontend developers handing off client websites",
+  "type": "module",
+  "bin": {
+    "handover": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "generator.js",
+    "prompts.js",
+    "scanner.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "handover",
+    "frontend",
+    "client",
+    "documentation",
+    "developer",
+    "claude",
+    "ai"
+  ],
+  "author": "sabrkei",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "chalk": "^5.3.0",
+    "docx": "^8.5.0"
+  }
+}

package/prompts.js

@@ -0,0 +1,185 @@
+export function technicalHandoverPrompt(projectInfo, developerInfo) {
+  const { name, company, email, phone } = developerInfo
+  const date = new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' })
+
+  return `
+You are an expert technical writer generating a TECHNICAL HANDOVER DOCUMENT for a developer taking over a client website project.
+
+This document is written for a DEVELOPER (future maintainer) — be precise, thorough, and technically complete. They need to be able to pick this project up cold with no prior knowledge.
+
+Developer who built this project:
+- Name: ${name || '[Developer Name]'}
+${company ? `- Company: ${company}` : ''}
+- Email: ${email || '[Developer Email]'}
+${phone ? `- Phone: ${phone}` : ''}
+- Handover date: ${date}
+
+The following context has been automatically scanned from the project files (package.json, config files, folder structure, environment variable keys, deploy configs, README, CSS colors, etc.). Use this to generate a document specific to THIS project. Do not invent or use generic placeholders — if a specific detail is not in the scanned data, note it as "[to be confirmed]".
+
+${projectInfo || '[No project data available]'}
+
+Generate a complete technical handover document with ALL of the following sections:
+
+---
+
+# [Project Name] — Technical Handover Document
+
+**Prepared by:** ${name || '[Developer Name]'}${company ? ` · ${company}` : ''}${email ? ` · ${email}` : ''}${phone ? ` · ${phone}` : ''}
+**Handover Date:** ${date}
+**Project URL:** [Live URL — to be confirmed]
+**Repository:** [Repo URL — to be confirmed]
+
+---
+
+## 1. Tech Stack
+- List every technology, framework, library, and tool used
+- Include versions where known
+- Briefly explain the role of each in the project
+
+## 2. Project Structure
+- Full folder/file structure with explanations of what each directory contains
+- Location of key config files and what they control
+- Entry points and routing overview
+
+## 3. Local Development Setup
+- Prerequisites (Node version, package manager, etc.)
+- Step-by-step install and run instructions using exact terminal commands in code blocks
+- All environment variables required (keys only, no values) — what each one does
+
+## 4. Build & Deployment
+- Build command and output directory
+- Hosting provider and deployment method
+- CI/CD pipeline if applicable
+- Domain, DNS, and SSL details
+- How to roll back a broken deployment
+
+## 5. Third-Party Integrations & Services
+- Every external service, API, or plugin used
+- What each one does and where it is configured
+- Which accounts own these services
+
+## 6. Credentials & Access
+- Table of all accounts needed (service, URL, account owner, how to request access)
+- Environment variable names and their purpose
+- Access transfer checklist
+
+## 7. Known Issues & Technical Debt
+- Any bugs, limitations, or workarounds in the current codebase
+- TODO items or deferred improvements
+- Performance or SEO considerations
+
+## 8. Maintenance Guide
+- How to update npm dependencies safely
+- What to check after deploying changes
+- Renewal dates for domain, hosting, or licences if known
+
+## 9. Developer Handover Checklist
+- [ ] Repository access transferred or shared
+- [ ] All environment variables documented
+- [ ] Hosting and domain access transferred
+- [ ] Third-party service accounts handed over
+- [ ] Local dev environment tested and documented
+- [ ] Live site tested across browsers and devices
+- [ ] Analytics verified working
+- [ ] README updated
+
+---
+
+Format the entire document in clean, well-structured Markdown.
+Use code blocks for all terminal commands and code snippets.
+Use tables where appropriate (especially for credentials and dependencies).
+Be thorough and precise — this document is the sole reference for the incoming developer.
+`.trim()
+}
+
+export function nonTechnicalHandoverPrompt(projectInfo, developerInfo) {
+  const { name, company, email, phone } = developerInfo
+  const date = new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' })
+
+  return `
+You are an expert writer generating a NON-TECHNICAL HANDOVER DOCUMENT for a CLIENT receiving their completed website.
+
+This document is written for the BUSINESS OWNER or CLIENT — use plain English, a warm and reassuring tone, and absolutely no technical jargon. The client should feel confident and informed about what they own.
+
+Developer contact details:
+- Name: ${name || '[Developer Name]'}
+${company ? `- Company: ${company}` : ''}
+- Email: ${email || '[Developer Email]'}
+${phone ? `- Phone: ${phone}` : ''}
+- Handover date: ${date}
+
+The following context has been automatically scanned from the project files. Use this to generate a document specific to THIS project. Focus on what the client needs to know — not how it was built. If a specific detail is not available, note it as "[to be confirmed]".
+
+${projectInfo || '[No project data available]'}
+
+Generate a complete non-technical handover document with ALL of the following sections:
+
+---
+
+# [Project Name] — Your Website Handover Guide
+
+**Prepared by:** ${name || '[Developer Name]'}${company ? ` · ${company}` : ''}${email ? ` · ${email}` : ''}${phone ? ` · ${phone}` : ''}
+**Date:** ${date}
+
+---
+
+## 1. About Your Website
+- What your website does and who it is for (1–2 paragraphs, plain English)
+- The main pages or sections and what each one is for
+- Any special features the site has (contact forms, booking, e-commerce, blog, etc.)
+
+## 2. Your Website's Look & Feel
+- The overall design style and visual identity
+- Colours used on the site (mention specific colours by name and hex code if detected in the project)
+- Fonts used
+- Any branding guidelines to keep in mind when making future updates
+
+## 3. What You Own
+- A plain-English summary of everything handed over: the website, domain, hosting, code, and content
+- Who owns what and what that means for you
+
+## 4. Logging Into Your Website
+- How to access and log in to any admin area or CMS (plain steps, no jargon)
+- What you can safely update yourself
+- What you should NOT change without speaking to a developer first
+
+## 5. How to Update Your Content
+- Step-by-step instructions for common tasks (e.g. updating text, adding images, publishing a blog post)
+- Keep instructions simple and numbered
+- Include a note about backing up before making changes
+
+## 6. Your Accounts & Passwords
+- List of all accounts the client now owns (hosting, domain, CMS, email, analytics, etc.)
+- Reminder to store passwords securely and change them after handover
+- Note: actual passwords should be shared separately and securely — not in this document
+
+## 7. Keeping Your Website Healthy
+- What needs renewing and approximately when (domain name, hosting plan, SSL certificate, any paid plugins)
+- How to tell if something on the site is broken
+- Simple monthly and yearly maintenance checklist
+
+## 8. Getting Help
+- When and how to contact your developer: ${name || '[Developer Name]'}${company ? ` (${company})` : ''}${email ? `, ${email}` : ''}${phone ? `, ${phone}` : ''}
+- What kinds of changes require a developer
+- Recommended process for requesting future updates
+
+## 9. Handover Sign-Off
+### Developer confirms:
+- [ ] All accounts and login details have been transferred
+- [ ] The live site has been reviewed and approved
+- [ ] This document has been discussed with the client
+
+### Client acknowledges:
+- [ ] I have received all login credentials securely
+- [ ] I understand how to update my website content
+- [ ] I know what I should not change without developer help
+- [ ] I know how to contact my developer for support
+
+---
+
+Write the entire document in plain, friendly English. Use short sentences and simple words.
+Avoid ALL technical jargon — if a technical term must be used, explain it in brackets immediately after.
+Use numbered lists for any step-by-step instructions.
+The tone should be warm, professional, and reassuring — the client should feel proud of their new website.
+`.trim()
+}

package/scanner.js

@@ -0,0 +1,250 @@
+import fs from 'fs'
+import path from 'path'
+
+const CONFIG_FILES = [
+  'vite.config.js', 'vite.config.ts',
+  'next.config.js', 'next.config.ts', 'next.config.mjs',
+  'nuxt.config.js', 'nuxt.config.ts',
+  'astro.config.js', 'astro.config.ts', 'astro.config.mjs',
+  'svelte.config.js',
+  'remix.config.js',
+  'tailwind.config.js', 'tailwind.config.ts',
+  'postcss.config.js',
+  'netlify.toml',
+  'vercel.json',
+  'render.yaml',
+  'railway.json',
+  '.htaccess',
+  'Dockerfile',
+  'docker-compose.yml',
+  'firebase.json',
+]
+
+const DEPLOY_WORKFLOW_DIR = '.github/workflows'
+
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function getEnvKeys(filePath) {
+  const content = readFileSafe(filePath)
+  if (!content) return []
+  return content
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#') && l.includes('='))
+    .map(l => l.split('=')[0].trim())
+}
+
+function getFolderStructure(dir, depth = 0, maxDepth = 2) {
+  if (depth > maxDepth) return []
+  const ignore = new Set(['node_modules', '.git', '.next', '.nuxt', 'dist', 'build', '.cache', 'coverage', '.turbo'])
+  let entries = []
+  try {
+    const items = fs.readdirSync(dir, { withFileTypes: true })
+    for (const item of items) {
+      if (ignore.has(item.name) || item.name.startsWith('.')) continue
+      const indent = '  '.repeat(depth)
+      if (item.isDirectory()) {
+        entries.push(`${indent}${item.name}/`)
+        entries.push(...getFolderStructure(path.join(dir, item.name), depth + 1, maxDepth))
+      } else {
+        entries.push(`${indent}${item.name}`)
+      }
+    }
+  } catch {}
+  return entries
+}
+
+function detectFramework(deps = {}, devDeps = {}) {
+  const all = { ...deps, ...devDeps }
+  if (all['next']) return 'Next.js'
+  if (all['nuxt'] || all['nuxt3']) return 'Nuxt'
+  if (all['@astrojs/core'] || all['astro']) return 'Astro'
+  if (all['@sveltejs/kit']) return 'SvelteKit'
+  if (all['svelte']) return 'Svelte'
+  if (all['@remix-run/react']) return 'Remix'
+  if (all['gatsby']) return 'Gatsby'
+  if (all['react']) return 'React'
+  if (all['vue']) return 'Vue'
+  if (all['angular']) return 'Angular'
+  return null
+}
+
+export function scanProject(dir = process.cwd()) {
+  const sections = []
+
+  // --- package.json ---
+  const pkgPath = path.join(dir, 'package.json')
+  let pkg = null
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(readFileSafe(pkgPath))
+      const framework = detectFramework(pkg.dependencies, pkg.devDependencies)
+      sections.push(`## package.json`)
+      sections.push(`Name: ${pkg.name || 'unknown'}`)
+      if (pkg.description) sections.push(`Description: ${pkg.description}`)
+      if (pkg.version) sections.push(`Version: ${pkg.version}`)
+      if (framework) sections.push(`Detected framework: ${framework}`)
+      if (pkg.engines?.node) sections.push(`Node requirement: ${pkg.engines.node}`)
+
+      if (pkg.scripts && Object.keys(pkg.scripts).length) {
+        sections.push(`\nScripts:`)
+        for (const [k, v] of Object.entries(pkg.scripts)) {
+          sections.push(`  ${k}: ${v}`)
+        }
+      }
+
+      const deps = Object.keys(pkg.dependencies || {})
+      const devDeps = Object.keys(pkg.devDependencies || {})
+      if (deps.length) sections.push(`\nDependencies: ${deps.join(', ')}`)
+      if (devDeps.length) sections.push(`Dev dependencies: ${devDeps.join(', ')}`)
+    } catch {}
+  }
+
+  // --- Package manager ---
+  let pm = 'npm'
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) pm = 'yarn'
+  else if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) pm = 'pnpm'
+  else if (fs.existsSync(path.join(dir, 'bun.lockb'))) pm = 'bun'
+  sections.push(`\nPackage manager: ${pm}`)
+
+  // --- Environment variables ---
+  const envExampleKeys = getEnvKeys(path.join(dir, '.env.example'))
+  const envLocalKeys = getEnvKeys(path.join(dir, '.env.local'))
+  const envKeys = getEnvKeys(path.join(dir, '.env'))
+  const allEnvKeys = [...new Set([...envExampleKeys, ...envLocalKeys, ...envKeys])]
+  if (allEnvKeys.length) {
+    sections.push(`\n## Environment Variables (keys only)`)
+    allEnvKeys.forEach(k => sections.push(`  ${k}`))
+  }
+
+  // --- Config files ---
+  for (const file of CONFIG_FILES) {
+    const filePath = path.join(dir, file)
+    if (fs.existsSync(filePath)) {
+      const content = readFileSafe(filePath)
+      if (content && content.length < 4000) {
+        sections.push(`\n## ${file}`)
+        sections.push('```')
+        sections.push(content.trim())
+        sections.push('```')
+      } else if (content) {
+        sections.push(`\n## ${file} (truncated)`)
+        sections.push('```')
+        sections.push(content.trim().slice(0, 4000) + '\n...')
+        sections.push('```')
+      }
+    }
+  }
+
+  // --- GitHub Actions workflows ---
+  const workflowDir = path.join(dir, DEPLOY_WORKFLOW_DIR)
+  if (fs.existsSync(workflowDir)) {
+    try {
+      const files = fs.readdirSync(workflowDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+      for (const file of files) {
+        const content = readFileSafe(path.join(workflowDir, file))
+        if (content) {
+          sections.push(`\n## .github/workflows/${file}`)
+          sections.push('```yaml')
+          sections.push(content.trim().slice(0, 3000))
+          sections.push('```')
+        }
+      }
+    } catch {}
+  }
+
+  // --- README ---
+  const readmePath = path.join(dir, 'README.md')
+  if (fs.existsSync(readmePath)) {
+    const content = readFileSafe(readmePath)
+    if (content) {
+      sections.push(`\n## README.md`)
+      sections.push(content.trim().slice(0, 3000))
+    }
+  }
+
+  // --- License ---
+  for (const f of ['LICENSE', 'LICENSE.md', 'LICENSE.txt']) {
+    const p = path.join(dir, f)
+    if (fs.existsSync(p)) {
+      const content = readFileSafe(p)
+      if (content) {
+        sections.push(`\n## ${f}`)
+        sections.push(content.trim().slice(0, 500))
+      }
+      break
+    }
+  }
+
+  // --- CSS color detection ---
+  const cssColors = extractColors(dir)
+  if (cssColors.length) {
+    sections.push(`\n## Detected colours (from CSS/config files)`)
+    cssColors.forEach(c => sections.push(`  ${c}`))
+  }
+
+  // --- Folder structure ---
+  const structure = getFolderStructure(dir)
+  if (structure.length) {
+    sections.push(`\n## Project folder structure`)
+    sections.push(structure.join('\n'))
+  }
+
+  return sections.join('\n')
+}
+
+function extractColors(dir) {
+  const colors = new Set()
+  const hexPattern = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g
+  const cssVarColorPattern = /(--[\w-]*color[\w-]*|--[\w-]*bg[\w-]*|--[\w-]*primary[\w-]*|--[\w-]*secondary[\w-]*):\s*([^;}\n]+)/gi
+  const cssExtensions = ['.css', '.scss', '.sass', '.less']
+
+  function scanFile(filePath) {
+    const content = readFileSafe(filePath)
+    if (!content) return
+    let match
+    while ((match = hexPattern.exec(content)) !== null) {
+      colors.add(`#${match[1].toUpperCase()}`)
+    }
+    while ((match = cssVarColorPattern.exec(content)) !== null) {
+      colors.add(`${match[1].trim()}: ${match[2].trim()}`)
+    }
+  }
+
+  function walkDir(d, depth = 0) {
+    if (depth > 3) return
+    const ignore = new Set(['node_modules', '.git', '.next', '.nuxt', 'dist', 'build', '.cache'])
+    try {
+      const items = fs.readdirSync(d, { withFileTypes: true })
+      for (const item of items) {
+        if (ignore.has(item.name) || item.name.startsWith('.')) continue
+        const full = path.join(d, item.name)
+        if (item.isDirectory()) {
+          walkDir(full, depth + 1)
+        } else if (cssExtensions.includes(path.extname(item.name).toLowerCase())) {
+          scanFile(full)
+        }
+      }
+    } catch {}
+  }
+
+  walkDir(dir)
+
+  // Also check tailwind config for color definitions
+  for (const twConfig of ['tailwind.config.js', 'tailwind.config.ts']) {
+    const content = readFileSafe(path.join(dir, twConfig))
+    if (!content) continue
+    let match
+    while ((match = hexPattern.exec(content)) !== null) {
+      colors.add(`#${match[1].toUpperCase()}`)
+    }
+  }
+
+  return [...colors].slice(0, 40) // cap at 40 to avoid flooding context
+}