# Markdown linting
npx markdownlint **/*.md

# Spell check
npx cspell "**/*.md"

# Link checking
npx markdown-link-check docs/**/*.md

# Build documentation site (if applicable)
npm run docs:build
mkdocs build

# Live preview
npm run docs:serve
mkdocs serve

# Static site preview
python -m http.server 8000 -d docs/

## POST /api/users

Creates a new user account.

**Authentication:** Required (Bearer token)

**Request Body:**
```json
{
  "email": "user@example.com",    // Required, must be valid email
  "password": "secure123",        // Required, min 8 characters
  "name": "John Doe"              // Required
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z"
}

curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure123",
    "name": "John Doe"
  }'

### User Guide Pattern

```markdown
# Setting Up User Authentication

This guide walks you through enabling user authentication in your application.

## Prerequisites

- Node.js 18+ installed
- Database configured
- Admin access to the application

## Step 1: Install Required Packages

```bash
npm install bcrypt jsonwebtoken express-session

JWT_SECRET=your-secret-key-here
SESSION_TIMEOUT=3600

const authMiddleware = require('./middleware/auth');
app.use(authMiddleware);

### Code Documentation Pattern

```kotlin
/**
 * Creates a new user account with the provided information.
 *
 * This function validates the user data, hashes the password using bcrypt,
 * and persists the user to the database. Email uniqueness is enforced at
 * the database level.
 *
 * @param email User's email address (must be valid format and unique)
 * @param password Plain text password (min 8 characters, will be hashed)
 * @param name User's full name
 * @return Created user with generated ID and timestamps
 * @throws ValidationException if email format is invalid or password too short
 * @throws DuplicateEmailException if email already registered
 * @throws DatabaseException if database operation fails
 *
 * @example
 * ```kotlin
 * val user = userService.createUser(
 *     email = "john@example.com",
 *     password = "secure123",
 *     name = "John Doe"
 * )
 * println(user.id)  // UUID generated by database
 * ```
 *
 * @see User
 * @see validateEmail
 * @see hashPassword
 */
fun createUser(email: String, password: String, name: String): User {
    // Implementation
}

⚠️ BLOCKED - Requires Senior Engineer

Issue: [Specific problem - implementation incomplete, unclear behavior, etc.]

Attempted Research:
- [What sources you checked]
- [What you tried to find out]
- [Why it didn't work]

Blocked By: [Task ID / incomplete implementation / unclear requirements]

Partial Progress: [What documentation you DID complete]

Requires: [What needs to happen to unblock documentation]

Edit config/auth.js and set:
```javascript
module.exports = {
  jwtSecret: 'your-secret-here',
  tokenExpiry: '24h'
};

### Include Examples

Every documented feature should have:
- Code example showing usage
- Expected output
- Common use cases

### Anticipate Questions

After each instruction, ask:
- What could go wrong here?
- What might be unclear?
- What would I wonder about?

Add troubleshooting for those questions.

## Common Patterns to Follow

1. **Start with overview** - what it is, why it matters
2. **Prerequisites first** - what user needs before starting
3. **Step-by-step instructions** - numbered, one action per step
4. **Examples that work** - test all code examples
5. **Troubleshooting section** - common problems and solutions
6. **Clear formatting** - headings, code blocks, lists
7. **Links to related docs** - help users find more information

## What NOT to Do

❌ Don't use jargon without explaining it
❌ Don't assume prior knowledge
❌ Don't skip error cases
❌ Don't provide untested code examples
❌ Don't use vague terms ("simply", "just", "obviously")
❌ Don't forget to update docs when code changes
❌ Don't document implementation details users don't need

## Focus Areas

When reading task sections, prioritize:
- `requirements` - What needs documenting
- `context` - Purpose and audience
- `documentation` - Existing docs to update
- `implementation` - How it actually works

## Remember

- **Accuracy is critical** - test everything you document
- **Clarity over cleverness** - simple language wins
- **Examples are essential** - every feature needs working examples
- **Update, don't duplicate** - check if docs already exist
- **Test your instructions** - follow them yourself
- **Report blockers promptly** - missing information, incomplete features
- **Users read docs when stuck** - be helpful and thorough

## Additional Resources

For deeper patterns and examples, see:
- **PATTERNS.md** - Advanced documentation patterns, style guides (load if needed)
- **BLOCKERS.md** - Detailed documentation-specific blockers (load if stuck)
- **examples.md** - Complete documentation examples (load if uncertain)