Docs From The Dead

Read any existing documentation and classify its tone:

• First person casual: "I built this because..." → maintain first person
• First person formal: "I developed this library to..." → maintain formal first person
• Third person technical: "This library provides..." → maintain third person
• Casual with emojis: "🚀 Awesome Tool!" → match the energy and emoji usage
• No existing tone: Default to third person technical

Step 3: Reconstruct README.md

The new README.md must include ALL of these sections:

Section 1: What it does

• One paragraph, maximum 3 sentences
• Inferred from: package.json description field + main entry point analysis
• Read the main entry point (main field in package.json) and summarize what the top-level exports do

Section 2: Why it was built

• Inferred from: repository name, original first commit message, any existing README fragments, package.json keywords

• git log --reverse --oneline | head -5  # first commits reveal intent
  

Section 3: Installation

Always include:

### Prerequisites
- Node.js [version from engines field or >=14]
- npm [version or >=6]

### Install
\`\`\`bash
npm install
\`\`\`

### Environment Variables
[Only if .env.example exists — list all variables with descriptions]

Section 4: Usage

• Generate at least 2 real code examples
• These MUST use the actual exported functions/classes from the entry point
• Do not invent fictional APIs

• const lib = require('./package-name');
  // Real usage based on actual exports
  

Section 5: Architecture

• Generate a plain-text folder structure diagram:

  project-name/
  ├── src/           # Source code
  │   ├── index.js   # Entry point
  │   └── utils/     # Utility functions
  ├── tests/         # Test files
  ├── package.json   # Dependencies
  └── README.md      # This file
  

• Include a one-line description for each directory and key file
• Generated from:

  find . -not -path "./node_modules/*" -not -path "./.git/*" \
    -not -path "./dist/*" | head -50
  

Section 6: Contributing

Standard fork/PR workflow:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Section 7: Revival Notice

---

> 👻 **Revival Notice**: This repository was revived by 
> [GitGhost](https://github.com/open-gitagent/gitagent) on [ISO date].
> Original repository: [link to original]
> 
> *Every abandoned project deserves a second life.*

Step 4: Generate JSDoc for All Public Functions

For every exported function that lacks JSDoc, generate documentation:

/**
 * [Description inferred from function name and body]
 * 
 * @param {type} paramName - [Description inferred from name and usage]
 * @returns {type} [Description of return value]
 * @example
 * // [Real usage example from codebase or inferred]
 * const result = functionName(exampleInput);
 * 
 * @generated by GitGhost
 */

Rules:

• Always include: @param, @returns, @example
• Include when applicable: @throws, @async, @deprecated
• Type inference priority: TypeScript types > JSDoc types > inferred from usage
• Mark generated: Always add @generated by GitGhost as the last tag
• Don't overwrite: If a function already has JSDoc, leave it untouched

Step 5: Check for Missing Documentation Files

Look for common docs that should exist:

Step 6: Preserve Original Content

When rewriting README.md:

1. If the original README has content, preserve any sections that contain specific domain knowledge (API keys, deployment URLs, business logic)
2. Add a <!-- Original README content preserved below --> marker
3. Place the original content in a collapsed <details> section at the bottom:

   <details>
   <summary>Original README (preserved)</summary>
   
   [original content here]
   
   </details>