{"id":34501322,"url":"https://github.com/maxberko/max-doc-ai","last_synced_at":"2026-04-12T03:03:30.213Z","repository":{"id":329956556,"uuid":"1121122511","full_name":"maxberko/max-doc-ai","owner":"maxberko","description":"Automate product documentation with Claude Code - screenshots, docs, and announcements","archived":false,"fork":false,"pushed_at":"2025-12-22T17:48:31.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-24T00:47:26.530Z","etag":null,"topics":["automation","claude-code","documentation-automation","knowledge-base","playwright","pylon","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxberko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T13:25:43.000Z","updated_at":"2025-12-22T17:48:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxberko/max-doc-ai","commit_stats":null,"previous_names":["maxberko/max-doc-ai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maxberko/max-doc-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxberko%2Fmax-doc-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxberko%2Fmax-doc-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxberko%2Fmax-doc-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxberko%2Fmax-doc-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxberko","download_url":"https://codeload.github.com/maxberko/max-doc-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxberko%2Fmax-doc-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27992996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","claude-code","documentation-automation","knowledge-base","playwright","pylon","python"],"created_at":"2025-12-24T02:00:53.011Z","updated_at":"2025-12-31T00:43:57.833Z","avatar_url":"https://github.com/maxberko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# max-doc-AI\n\nAutomate product documentation workflows with Claude Code.\n\nmax-doc-AI is a collection of Claude Code skills that automate documentation creation, screenshot capture, and customer announcements. Point it at your codebase, and it handles the documentation workflow end-to-end.\n\n## What It Does\n\nmax-doc-AI provides 5 integrated Claude skills:\n\n- **📸 capture-screenshots** - Automated screenshot capture using Claude's Computer Use API\n- **📝 update-product-doc** - AI-generated documentation from your codebase\n- **☁️ sync-docs** - Upload images and sync to your knowledge base (Pylon, Zendesk, etc.)\n- **📢 create-changelog** - Generate customer announcements for Slack/Email\n- **🚀 create-release** - Orchestrate the complete release workflow\n\n## How It Works\n\n### 1. Codebase Research\nClaude explores your codebase to understand the feature implementation, patterns, and architecture.\n\n### 2. Screenshot Capture\nClaude's Computer Use API (or Google Gemini) provides visual browser automation with intelligent authentication and content verification for reliable screenshots. Choose between Anthropic Claude or Google Gemini based on your needs.\n\n### 3. Documentation Generation\nClaude writes comprehensive documentation including:\n- Feature overview\n- Configuration steps\n- Use cases\n- Embedded screenshots\n\n### 4. Knowledge Base Sync\nDocumentation and screenshots are synced to your knowledge base provider:\n- **Pylon**: Images → CDN (CloudFront URLs), Docs → KB (organized by collections)\n- **Zendesk**: Images → Help Center, Docs → Articles (organized by sections)\n- **Custom**: Extensible provider system for other platforms\n\n### 5. Customer Announcements\nGenerate targeted announcements:\n- **Slack**: Short, engaging format\n- **Email**: Detailed explanation with examples\n\n## Key Features\n\n- **Fully Automated** - One command generates complete release materials\n- **Codebase-Aware** - Claude researches your code to understand features\n- **Intelligent Screenshot Capture** - Computer Use API with visual authentication (supports Anthropic Claude \u0026 Google Gemini)\n- **Reliable Content Capture** - Claude waits naturally for pages to load and verifies content\n- **Multi-Provider KB Integration** - Works with Pylon, Zendesk, or custom providers\n- **Multi-Channel Announcements** - Generate Slack and email variations\n- **State Tracking** - Track what's synced to avoid duplicates\n\n## Quick Start\n\n### Prerequisites\n\n- [Claude Code](https://claude.com/claude-code) installed and configured\n- Python 3.8+\n- Knowledge base provider account (Pylon, Zendesk, or other supported platform)\n\n### Setting Up Claude\n\nBefore you can use max-doc-AI, you need to set up your Claude account and API key:\n\n#### 1. Create a Claude Account\n\nIf you don't have a Claude account yet:\n1. Visit [claude.ai](https://claude.ai)\n2. Sign up for an account (you can use Google, email, or other sign-in options)\n3. Verify your email address if required\n\n#### 2. Get Your Claude API Key\n\nTo use Claude Code and max-doc-AI, you'll need an API key:\n\n1. Go to [console.anthropic.com](https://console.anthropic.com)\n2. Sign in with your Claude account\n3. Navigate to **API Keys** in the left sidebar\n4. Click **Create Key**\n5. Give your key a descriptive name (e.g., \"max-doc-ai-local\")\n6. Copy the API key immediately (you won't be able to see it again)\n\n**Important:** Keep your API key secure and never commit it to version control.\n\n#### 3. Install Claude Code CLI\n\nInstall the Claude Code command-line tool:\n\n```bash\n# macOS/Linux\nbrew install anthropics/tap/claude\n\n# Or using npm\nnpm install -g @anthropic-ai/claude-code\n\n# Or using pip\npip install claude-code\n```\n\nVerify the installation:\n```bash\nclaude --version\n```\n\n#### 4. Configure Your API Key\n\nSet up your API key for Claude Code:\n\n```bash\n# Option 1: Interactive setup (recommended)\nclaude auth login\n\n# Option 2: Set environment variable\nexport ANTHROPIC_API_KEY=your-api-key-here\n\n# Option 3: Add to your shell profile for persistence\necho 'export ANTHROPIC_API_KEY=your-api-key-here' \u003e\u003e ~/.zshrc  # or ~/.bashrc\nsource ~/.zshrc  # or ~/.bashrc\n```\n\n**Verify your setup:**\n```bash\nclaude run \"print hello world\"\n```\n\nIf you see a response from Claude, you're all set!\n\n**Usage Costs:** Claude API usage is billed based on tokens processed. Check current pricing at [anthropic.com/pricing](https://www.anthropic.com/pricing). max-doc-AI operations typically cost between $0.10-$0.50 per feature release depending on codebase size.\n\n### Installation\n\n#### Option 1: Interactive Setup (Recommended)\n\nThe easiest way to get started:\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/maxberko/max-doc-ai.git\ncd max-doc-ai\n\n# 2. Run the interactive setup wizard\npython3 scripts/setup.py\n\n# 3. Verify everything works\npython3 scripts/health_check.py\n\n# 4. Create your first release\nclaude \"Create a release for [your feature name]\"\n```\n\n**Done!** You're ready to go in under 5 minutes. 🚀\n\nThe setup wizard will:\n- Check your system requirements\n- Help you choose a knowledge base provider (Pylon, Zendesk, etc.)\n- Collect your credentials securely\n- Create configuration files automatically\n- Verify your connection\n- Show you exactly what to do next\n\nFor detailed information, see **[GETTING_STARTED.md](GETTING_STARTED.md)**.\n\n#### Option 2: Manual Configuration (Advanced)\n\nFor advanced users who prefer manual setup:\n\n```bash\n# 1. Clone and install dependencies\ngit clone https://github.com/maxberko/max-doc-ai.git\ncd max-doc-ai\npip install -r requirements.txt\n\n# 2. Copy configuration templates\ncp config.example.yaml config.yaml\ncp .env.example .env\n\n# 3. Configure your environment\n# Edit .env with your credentials:\n#   - ANTHROPIC_API_KEY=your-api-key\n#   - SCREENSHOT_USER=your-product-username\n#   - SCREENSHOT_PASS=your-product-password\n#   - PYLON_API_KEY=your-pylon-key\n#   (and other required keys)\n\n# 4. Update config.yaml with your product details\n# See docs/computer-use-setup.md for detailed configuration\n\n# 5. Verify Computer Use setup\npython3 scripts/screenshot/test_computer_use.py\n```\n\n**macOS Users**: Grant accessibility permissions for pyautogui in System Preferences → Security \u0026 Privacy → Accessibility.\n\n**See**: [Computer Use Setup Guide](docs/computer-use-setup.md) for complete installation instructions.\n\n### Basic Usage\n\nComplete release workflow:\n```\n@claude Create a release for the Dashboards feature\n```\n\n**Interactive Pre-Flight:**\nClaude will first ask you a series of questions to configure the release:\n- How to provide feature information (PRD text, short description, or feature name)\n- Repository source (current codebase or external GitHub repo)\n- Release date (today or specify a date in YYYY-MM-DD format)\n\n**Automated Execution:**\nAfter collecting information, Claude will automatically:\n1. Research the feature in your codebase (or clone external repo)\n2. Capture product screenshots\n3. Generate comprehensive documentation\n4. Upload screenshots to your KB provider's CDN\n5. Sync documentation to your knowledge base\n6. Create customer announcements\n\n**Output Structure:**\n\n**IMPORTANT:** All generated files are saved to the `./output/` directory. Nothing is saved outside this folder.\n\n```\noutput/\n├── features/YYYY-MM-DD_feature-name/\n│   └── feature-name.md              # Complete documentation\n├── changelogs/YYYY-MM-DD/\n│   └── feature-name/\n│       ├── slack-announcement.md    # Slack announcement\n│       ├── email-announcement.md    # Email announcement\n│       └── README.md                # Release metadata\n├── screenshots/\n│   └── feature-name-*.png           # Product screenshots\n└── sync-state.json                  # KB sync state tracking\n```\n\n**Dated Organization:** Features and changelogs are organized by release date (YYYY-MM-DD format) for easy tracking and archiving.\n\nOr use individual skills:\n```\n@claude Skill: capture-screenshots\nFeature: User Authentication\nURLs: /login, /signup, /settings\n\n@claude Skill: update-product-doc\nFeature: User Authentication\nCategory: getting-started\n\n@claude Skill: create-changelog\nFeature: User Authentication\nDocumentation URL: [Your KB URL]\n```\n\n## Documentation\n\n### Getting Started\n- **[Computer Use Setup](docs/computer-use-setup.md)** - Set up Claude's Computer Use API for screenshots\n- **[Setup Guide](docs/setup.md)** - Complete installation and configuration\n- **[Usage Guide](docs/usage.md)** - How to use each skill\n\n### Advanced\n- **[Configuration Reference](docs/configuration.md)** - All configuration options\n- **[KB Providers Guide](KB_PROVIDERS.md)** - Multi-provider system and adding new providers\n- **[Release Workflow](RELEASE_WORKFLOW_INTEGRATION.md)** - Complete release process documentation\n- **[Demo Product](docs/demo-product.md)** - Example documentation workflow\n\n## Project Structure\n\n```\nmax-doc-ai/\n├── .claude/\n│   └── skills/              # Claude Code skills\n│       ├── create-release/\n│       ├── capture-screenshots/\n│       ├── update-product-doc/\n│       ├── sync-docs/\n│       └── create-changelog/\n├── scripts/\n│   ├── config.py            # Configuration loader\n│   ├── setup.py             # Interactive setup wizard\n│   ├── health_check.py      # System health validation\n│   ├── auth_manager.py      # Browser authentication\n│   ├── kb/                  # Generic KB sync scripts\n│   │   ├── sync.py          # Documentation sync (multi-provider)\n│   │   └── upload.py        # Image upload (multi-provider)\n│   ├── pylon/               # Pylon-specific utilities\n│   ├── screenshot/          # Screenshot capture\n│   │   └── capture.py       # Playwright automation\n│   └── utils/               # Utilities\n│       ├── state.py         # Sync state tracking\n│       ├── github_helper.py # GitHub repository integration\n│       └── migrate_output.py # Migration helper\n├── utils/                   # Core utilities\n│   ├── kb_providers/        # Knowledge base providers\n│   │   ├── base.py          # Abstract provider interface\n│   │   ├── pylon.py         # Pylon implementation\n│   │   └── zendesk.py       # Zendesk implementation\n│   ├── doc_inventory.py     # Documentation discovery\n│   ├── friendly_errors.py   # User-friendly error messages\n│   └── skill_validator.py   # Skill registration validator\n├── output/                  # ALL GENERATED FILES GO HERE\n│   ├── features/            # Documentation: YYYY-MM-DD_feature-name/\n│   ├── changelogs/          # Announcements: YYYY-MM-DD/feature-name/\n│   ├── screenshots/         # All product screenshots\n│   └── sync-state.json      # KB sync state tracking\n├── demo/                    # Example documentation (reference only)\n│   └── docs/\n│       └── product_documentation/\n├── docs/                    # Setup guides\n├── config.example.yaml      # Configuration template\n├── .env.example             # Environment variables template\n└── requirements.txt         # Python dependencies\n```\n\n## Configuration\n\nThe system is configured via two files:\n\n**config.yaml** - Product and workflow settings\n```yaml\nproduct:\n  name: \"YourProduct\"\n  url: \"https://app.yourproduct.com\"\n\nscreenshots:\n  viewport_width: 1280\n  viewport_height: 800\n  model: \"claude-sonnet-4-5\"\n  auth:\n    enabled: true\n    type: \"sso\"\n    login_url: \"${PRODUCT_URL}/login\"\n    username: \"${SCREENSHOT_USER}\"\n    password: \"${SCREENSHOT_PASS}\"\n    sso_provider: \"google\"\n\n# Knowledge Base Provider Configuration\nknowledge_base:\n  provider: \"pylon\"  # or \"zendesk\", \"confluence\", etc.\n\n  providers:\n    pylon:\n      api_key: \"${PYLON_API_KEY}\"\n      kb_id: \"${PYLON_KB_ID}\"\n      author_id: \"${PYLON_AUTHOR_ID}\"\n      collections:\n        getting-started: \"${COLLECTION_GETTING_STARTED_ID}\"\n        features: \"${COLLECTION_FEATURES_ID}\"\n\n    zendesk:\n      subdomain: \"${ZENDESK_SUBDOMAIN}\"\n      email: \"${ZENDESK_EMAIL}\"\n      api_token: \"${ZENDESK_API_TOKEN}\"\n      sections:\n        getting-started: \"${ZENDESK_SECTION_GETTING_STARTED}\"\n        features: \"${ZENDESK_SECTION_FEATURES}\"\n```\n\n**.env** - API keys and credentials (never commit this!)\n```bash\n# AI Provider API Keys (you need at least ONE)\n# Anthropic Claude (default)\nANTHROPIC_API_KEY=sk-ant-api03-xxxxx\n# Google Gemini (alternative - more cost-effective)\n# GOOGLE_API_KEY=AIza-xxxxx\n\n# Screenshot Authentication\nSCREENSHOT_USER=your-username@example.com\nSCREENSHOT_PASS=your-password\n\n# Pylon (if using Pylon)\nPYLON_API_KEY=pylon_api_xxxxx\nPYLON_KB_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nPYLON_AUTHOR_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nCOLLECTION_FEATURES_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n\n# Zendesk (if using Zendesk)\nZENDESK_SUBDOMAIN=yourcompany\nZENDESK_EMAIL=your-email@example.com\nZENDESK_API_TOKEN=xxxxxxxxxxxxxxxxxxxxx\nZENDESK_SECTION_FEATURES=xxxxx\n```\n\nSee [Configuration Reference](docs/configuration.md) for all options.\n\n## Use Cases\n\n### Product Teams\n- Automate release documentation\n- Keep KB in sync with product\n- Generate consistent customer communications\n\n### Developer Relations\n- Document new features as they ship\n- Create educational content from code\n- Maintain up-to-date product guides\n\n### Technical Writers\n- Accelerate documentation creation\n- Ensure technical accuracy from code\n- Manage multi-channel content distribution\n\n## Requirements\n\n- **Claude Code** - The CLI tool that runs the skills\n- **Python 3.8+** - For scripts and automation\n- **Anthropic API Key** - For Computer Use API (screenshot automation)\n- **Knowledge Base Provider** - One of:\n  - Pylon (knowledge base and CDN hosting)\n  - Zendesk (help center and articles)\n  - Other supported platforms (see [KB_PROVIDERS.md](KB_PROVIDERS.md))\n- **Product Credentials** - Username/password for visual authentication during screenshot capture\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone and install dependencies\ngit clone https://github.com/maxberko/max-doc-ai.git\ncd max-doc-ai\npip install -r requirements.txt\n\n# Configure for your test environment\npython3 scripts/setup.py               # Interactive setup\n# OR manually:\n# cp config.example.yaml config.yaml\n# cp .env.example .env\n# Edit with your test KB credentials\n\n# Test system health\npython3 scripts/health_check.py        # Run all health checks\n\n# Test individual components\npython3 scripts/config.py              # Verify config\npython3 scripts/kb/sync.py discover    # Test doc discovery\npython3 scripts/utils/state.py         # Check state tracking\n```\n\n## Roadmap\n\n**Completed:**\n- [x] Multi-provider knowledge base support (Pylon, Zendesk, extensible)\n- [x] Interactive setup wizard\n- [x] Comprehensive health check system\n- [x] Documentation discovery and tracking\n\n**Planned:**\n- [ ] Additional KB providers (Confluence, Notion, GitBook)\n- [ ] Support additional CDN providers (Cloudinary, S3)\n- [ ] Additional announcement channels (Discord, Teams)\n- [ ] Video recording support (demo workflows)\n- [ ] Multi-language documentation support\n- [ ] Versioned documentation (per release)\n\n## Troubleshooting\n\n**Configuration issues:**\n- Run `python3 scripts/health_check.py` to diagnose problems\n- Run `python3 scripts/setup.py` to reconfigure\n\n**Screenshots are blank/empty:**\n- Re-run `python3 scripts/auth_manager.py` to refresh auth session\n- Check viewport size matches your product's responsive breakpoints\n\n**Knowledge base sync errors:**\n- Verify API credentials in `.env` are correct and active\n- Check collection/section IDs match what exists in your KB\n- Run `python3 scripts/kb/sync.py status` to check sync state\n- See [KB_PROVIDERS.md](KB_PROVIDERS.md) for provider-specific troubleshooting\n\n**Claude can't find feature:**\n- Provide more context about code location\n- Check that feature code is committed\n- Ensure Claude has access to the codebase\n\nSee [GETTING_STARTED.md](GETTING_STARTED.md#troubleshooting) for more solutions.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n**Key points:**\n- Free to use, modify, and distribute\n- Patent protection included\n- Derivative works must also be GPL v3\n- Source code must be made available with distributions\n\nFor the full license text, visit: https://www.gnu.org/licenses/gpl-3.0.txt\n\n## Acknowledgments\n\nBuilt with:\n- [Claude Code](https://claude.com/claude-code) - AI-powered CLI\n- [Playwright](https://playwright.dev/) - Browser automation\n\nSupported knowledge base platforms:\n- [Pylon](https://usepylon.com) - Knowledge base and CDN\n- [Zendesk](https://www.zendesk.com/) - Help center platform\n- Extensible architecture for custom providers\n\n---\n\n**Made with Claude Code**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxberko%2Fmax-doc-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxberko%2Fmax-doc-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxberko%2Fmax-doc-ai/lists"}