Metadata-Version: 2.4
Name: tastehq
Version: 0.1.0
Summary: One-liner CLI to pipe any brand's DESIGN.md from TasteHQ to stdout
Project-URL: Homepage, https://taste-hq.vercel.app
Project-URL: Repository, https://github.com/simoneleonelli/taste-hq
Author: TasteHQ
License: MIT
Keywords: brand,cli,design,design-tokens,style-guide,tastehq
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# tastehq (Python)

One-liner CLI to pipe any brand's DESIGN.md from [tasteHQ](https://taste-hq.vercel.app) to stdout. Also scores URLs against brand grammars, ingests external URLs into the grammar, and bootstraps `AGENTS.md` for any project that wants to anchor its agentic workflows to a brand's taste.

## Install

The PyPI package will land with v1.0 — `pip install tastehq` will work then. Until then, editable install from source:

```bash
git clone https://github.com/MustBeSimo/tasteHQ.git
cd tasteHQ
pip install -e cli/python
```

That registers the `tastehq` binary on your PATH.

## Usage

```
tastehq <slug>                          Print brand DESIGN.md to stdout
tastehq <slug> --json                   Print full JSON entry
tastehq list                            List all brands (tab-separated)
tastehq list --mood <mood>              Filter list by mood tag
tastehq search <query>                  Lexical search across the catalog
tastehq diff <slug1> <slug2>            Markdown table comparing two brands
tastehq judge <url> --target <brand>    Score URL against a brand's grammar
tastehq import <url>                    Extract URL → grammar v2 vector
tastehq init <slug>                     Bootstrap AGENTS.md in current dir
tastehq --help                          Show help
```

## Examples

```bash
# Pipe Stripe's design doc to stdout
tastehq stripe

# Full JSON entry
tastehq stripe --json

# List all brands
tastehq list

# Filter by mood
tastehq list --mood editorial

# Search
tastehq search "warm beige"

# Diff two brands
tastehq diff stripe linear

# Score a URL against Stripe's grammar
tastehq judge https://example.com --target stripe

# Ingest any URL into a grammar v2 vector
tastehq import https://example.com

# Pipe into a file
tastehq anthropic > anthropic-design.md

# Run without install
python cli/python/tastehq_cli.py stripe
```

## Bootstrap AGENTS.md

`tastehq init <slug>` writes a ready-to-commit `AGENTS.md` to the current directory, declaring the brand whose taste your agentic workflows should target. The file is the canonical contract between your repo and any AI coding agent reading it — see the [AGENTS.md spec](https://taste-hq.vercel.app/docs/AGENTS-MD-SPEC.md).

```bash
# Bootstrap AGENTS.md for Stripe in the current directory
tastehq init stripe

# Custom output path
tastehq init stripe --out docs/AGENTS.md

# Overwrite an existing file
tastehq init stripe --force

# Print to stdout instead of writing (pipe-friendly)
tastehq init stripe --print | less

# Also install the Claude Skill at .claude/skills/tastehq.md
tastehq init stripe --skill
```

Exit codes:

| Code | Meaning |
|---|---|
| 0 | Wrote AGENTS.md successfully |
| 1 | Output file exists (re-run with `--force`) |
| 2 | Brand slug not found in the catalog |
| 3 | Network error reaching tasteHQ |

The write is atomic (tempfile + `os.replace`) so a failed or interrupted run never leaves a half-written file on disk.

## Requirements

- Python >= 3.8
- No external dependencies (stdlib only — `urllib.request`, `tempfile`, `os`)

## API

Wraps the public tasteHQ API at `https://taste-hq.vercel.app/api`:

| Endpoint | Description |
|---|---|
| `/api/styles.json` | Full catalog |
| `/api/styles/:slug.json` | Single brand JSON |
| `/api/styles/:slug/design.md` | Brand DESIGN.md |
| `/api/styles/:slug/agents.md` | Ready-to-commit AGENTS.md |
| `/api/score` | URL + target_brand → per-axis judge score |
| `/api/extract` | URL → grammar v2 vector |

## Publish checklist (v1.0)

- [ ] `pip install build twine`
- [ ] `python -m build`
- [ ] `twine upload dist/*`
- [ ] Tag release: `git tag v1.0.0 && git push --tags`
