docs: modernize README with AI-native positioning, demos, and Claude Code plugin

Nikolay Samokhvalovrequested to merge
docs/modern-readme-ai-focused into main

Summary

Modernizes the README to be attractive for AI-focused developers, with multiple interactive demos and clear AI integration paths.

Closes #103 (closed)

Key Changes

Hero Section

  • Centered header with flat-square badges (npm, license, PostgreSQL, coverage)
  • AI-native positioning — "built for humans and AI agents"
  • Battle-tested social proof (GitLab, Miro, Chewy, Suno, Supabase, Gadget)

Quick Start

  • Simple npx postgresai checkup command
  • Collapsible demo GIF showing real output

Full Monitoring Stack

  • Clarified Linux + Docker requirement
  • Mentions managed version at console.postgres.ai

Production-safe Section

  • Observer effect awareness (timeouts, row limits, non-blocking queries)
  • Battle-tested stats: dozens of TiB, hundreds of kTPS, millions of DB objects
  • prepare-db --print-sql preview

For AI Developers Section

  • Claude Code plugin — marketplace installation + /pgai:issues workflow with demo showing:
    • List open issues (with IDs)
    • Analyze specific issue and propose action plan
  • MCP Server — install command with demo GIF
  • CLI + LLM — piping examples with demo GIF

Collapsible Demo GIFs

Section File Description
Quick start demo-checkup.gif Express checkup
Claude Code demo-claude-code.gif Issues workflow (list + analyze)
MCP Server demo-mcp.gif Installation
CLI + LLM demo-llm.gif Piping to LLMs

What's Inside Table

  • Added Claude Code plugin and MCP server rows

Requirements

  • Clarified Node.js 18+ includes npm/npx
  • Linux machine with Docker for full stack

Tips Section

  • Short alias: npx pgai checkup
  • Managed version link

CLI Improvements

  • Better error message when check ID provided without connection string (pgai checkup H002 now shows specific error instead of generic help)
  • Tests added for argument parsing (check ID vs connection string recognition)
  • Documented secure password methods in Claude Code plugin (.pgpass, PGPASSFILE, PGPASSWORD)

New Files

  • assets/demo-*.gif — Demo recordings
  • scripts/demos/*.sh — Demo recording scripts
  • .claude/CLAUDE.md — Claude Code project instructions
  • .claude/commands/pgai:issues.md — Issues workflow slash command
  • .claude/commands/pgai:checkup.md — Health check slash command
  • .claude-plugin/marketplace.json — Claude Code marketplace

Test plan

  • All checkup commands tested with real database
  • Demo GIFs recorded with actual output
  • All external links verified
  • Claude Code plugin slash commands work
  • MCP server install works
  • New CLI tests pass

🤖 Generated with Claude Code

Edited by Nikolay Samokhvalov

Merge request reports