Metadata-Version: 2.4
Name: seokit
Version: 1.0.6
Summary: Claude Code toolkit for creating high-quality SEO articles
Author: nguyennguyenit
License: Copyright (c) 2025 nguyennguyenit. All Rights Reserved.
        
        PROPRIETARY SOFTWARE LICENSE
        
        This software and associated documentation files (the "Software") are the
        proprietary property of nguyennguyenit and are protected by copyright law.
        
        RESTRICTIONS:
        1. You may NOT copy, modify, merge, publish, distribute, sublicense, or sell
           copies of the Software without explicit written permission.
        2. You may NOT reverse engineer, decompile, or disassemble the Software.
        3. You may NOT use the Software for commercial purposes without a license.
        
        PERMITTED USE:
        - Personal, non-commercial evaluation only.
        - Usage requires compliance with all applicable laws.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
        DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
        
        For licensing inquiries, contact: nguyennguyenit
        
Project-URL: Homepage, https://github.com/nguyennguyenit/seokit
Project-URL: Documentation, https://github.com/nguyennguyenit/seokit#readme
Project-URL: Repository, https://github.com/nguyennguyenit/seokit.git
Project-URL: Issues, https://github.com/nguyennguyenit/seokit/issues
Keywords: seo,claude,ai,content,articles
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-docx>=0.8.11
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# SEOKit

[![PyPI version](https://badge.fury.io/py/seokit.svg)](https://pypi.org/project/seokit/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)

Claude Code toolkit for creating high-quality SEO articles.

## Installation

### Using pipx (Recommended)

```bash
# Install pipx if not already installed
sudo apt install pipx  # Ubuntu/Debian
# or: brew install pipx  # macOS

pipx install seokit
seokit setup  # Install slash commands to ~/.claude/commands/
```

### Using pip with virtual environment

```bash
python3 -m venv ~/.seokit-venv
~/.seokit-venv/bin/pip install seokit
echo 'alias seokit="~/.seokit-venv/bin/seokit"' >> ~/.bashrc
source ~/.bashrc
```

### Using pip (if no PEP 668 restriction)

```bash
pip install seokit
```

### On modern Linux (Ubuntu 23.04+, Debian 12+)

```bash
pip install seokit --break-system-packages
```

## Features

- Search Intent Analysis - Understand user needs via Perplexity API
- Competitor Research - Analyze top 10 ranking articles
- Outline Creation - Structure content following Google E-E-A-T guidelines
- Outline Optimization - Apply 80/20 content distribution rules
- Article Writing - Generate full articles with DOCX export

## Usage

After installation, SEOKit slash commands are available in Claude Code. Refer to the `.claude/commands/` directory for detailed usage of each command.

### Workflow

1. `/search-intent "keyword"` - Analyze search intent
2. `/top-article "keyword"` - Find top 10 competitor articles
3. `/create-outline` - Create structured outline
4. `/optimize-outline` - Optimize with 80/20 rule
5. `/write-seo` - Generate full article + DOCX

### Output Structure

```
your-project/
└── keyword-slug/           # Auto-created per keyword
    ├── search-intent.md
    ├── top-articles.md
    ├── outline.md
    ├── outline-optimized.md
    ├── article.md
    └── article.docx
```

## Commands

| Command | Description |
|---------|-------------|
| `/search-intent [keyword]` | Analyze search intent |
| `/top-article [keyword]` | Find top competitor articles |
| `/create-outline` | Create article outline |
| `/optimize-outline` | Optimize outline structure |
| `/write-seo` | Write full article |

## CLI Commands

```bash
seokit --help                   # Show help
seokit setup                    # Install slash commands
seokit config                   # Configure API key
seokit update                   # Update files (preserves .env, checklists)
seokit update -f                # Reset all files to defaults
seokit uninstall                # Remove SEOKit data and slash commands
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SEOKIT_HOME` | `~/.claude/seokit` | Global installation path |
| `SEOKIT_KEYWORD` | (empty) | Output folder name |
| `PERPLEXITY_API_KEY` | - | API key (required) |

## Requirements

- Python 3.10+
- Claude Code CLI
- Perplexity API key ([get one here](https://www.perplexity.ai/settings/api))

## Troubleshooting

### "PERPLEXITY_API_KEY not configured"

```bash
seokit config
# Or manually:
echo "PERPLEXITY_API_KEY=pplx-your-key" >> ~/.claude/seokit/.env
```

### Commands not found

Run `seokit setup` to install slash commands:

```bash
seokit setup
```

This copies the slash command files to `~/.claude/commands/`.

## Update

```bash
pip install -U seokit  # Update package
seokit update          # Update slash commands & checklists
```

Use `seokit update -f` to reset all files to defaults (overwrites checklists).

## Uninstall

```bash
seokit uninstall      # Remove SEOKit data and slash commands
pip uninstall seokit  # Remove the pip package

# On modern Linux with PEP 668:
pip uninstall seokit --break-system-packages
```

## Documentation

See `docs/` folder for detailed documentation:
- [Codebase Summary](docs/codebase-summary.md) - Architecture overview
- [Project Overview](docs/project-overview-pdr.md) - Product requirements
- [Code Standards](docs/code-standards.md) - Development guidelines

## License

Proprietary - see [LICENSE](LICENSE) for details.
