ducktap 0.1.0__tar.gz

ducktap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Tests
+        run: pytest -q

ducktap-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.eggs/
+dist/
+build/
+*.egg
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# DuckTap working dirs
+.ducktap/
+output/
+out/
+generated/
+*.duckdb
+*.sqlite
+*.sqlite3
+*.har
+
+# Secrets
+.env
+.env.local
+*.pem

ducktap-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# Agent notes for DuckTap
+
+## Build / test commands
+
+- Install dev deps: `pip install -e ".[dev]"`
+- Run unit tests: `pytest -q`
+- Lint: `ruff check src tests`
+- Type check (best effort): `mypy src/ducktap`
+
+## End-to-end smoke
+
+```bash
+ducktap press tests/fixtures/petstore.yaml --out ./out
+ducktap shipcheck petstore --out-dir ./out
+```
+
+## Layout
+
+- `src/ducktap/` — package
+- `src/ducktap/generator/templates/` — Jinja2 templates (use `StrictUndefined`)
+- `catalog/*.yaml` — recipe library
+- `skills/` — Claude Code skills that drive DuckTap itself
+
+## Conventions
+
+- Generated CLIs are named `<api>-dt-cli`; MCP servers `<api>-dt-mcp`;
+  Claude skills `ducktap-<api>`.
+- Discoverers and generators are plugins (see `docs/PLUGINS.md`); register them
+  with `ducktap.core.plugins.register_*`.
+- Don't break the `APISpec` schema casually — every generator depends on it.

ducktap-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-05-11
+
+Initial release. The lean loop end-to-end:
+
+- OpenAPI / HAR / browser-sniff discoverers
+- Python CLI + MCP server + skill generators
+- Multi-LLM (LiteLLM)
+- Plugin registry (entry points)
+- Scorecard + shipcheck
+- FastAPI dashboard
+- Catalog (petstore, github, stripe)

ducktap-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to DuckTap
+
+Thanks for your interest! DuckTap is MIT-licensed and welcomes PRs.
+
+## Dev setup
+
+```bash
+git clone https://github.com/zanni098/DuckTap
+cd ducktap
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev,sniff]"
+playwright install chromium    # optional, for browser-sniff
+pytest -q
+```
+
+## Adding a catalog entry
+
+1. Create `catalog/<name>.yaml` matching `src/ducktap/catalog/registry.py:CatalogEntry`.
+2. Run `ducktap catalog print <name>` to verify it generates.
+3. PR with the YAML and a one-line summary in `CHANGELOG.md`.
+
+## Adding a plugin (better!)
+
+See `docs/PLUGINS.md`. Publish as its own PyPI package and we'll list it in the
+README.
+
+## Commit style
+
+Conventional commits welcome but not required. PR titles like `feat(catalog): add Notion`, `fix(openapi): handle nullable enums`, `docs: …` work great.
+
+## Code style
+
+- `ruff check src tests` clean.
+- Type hints encouraged; not enforced by CI.
+- New code paths need at least one test.

ducktap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuckTap Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ducktap-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: ducktap
+Version: 0.1.0
+Summary: DuckTap — a CLI factory for AI agents. Print agent-native CLIs + MCP servers + skills from any API or website.
+Project-URL: Homepage, https://github.com/zanni098/DuckTap
+Project-URL: Repository, https://github.com/zanni098/DuckTap
+Project-URL: Issues, https://github.com/zanni098/DuckTap/issues
+Author: DuckTap Contributors
+License: MIT License
+        
+        Copyright (c) 2026 DuckTap Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,automation,cli,llm,mcp,openapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonref>=1.1
+Requires-Dist: litellm>=1.40
+Requires-Dist: mcp>=1.0
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: sniff
+Requires-Dist: mitmproxy>=11.0; extra == 'sniff'
+Requires-Dist: playwright>=1.45; extra == 'sniff'
+Description-Content-Type: text/markdown
+
+# DuckTap
+
+> **Tape any API to your agent in one command.**
+> DuckTap is a CLI factory for AI agents. Point it at an OpenAPI spec, a HAR
+> file, or a plain website, and it *prints* a Python CLI, an MCP server, and a
+> Claude/Cursor/Codex skill — wired up, cached, scored, ready to ship.
+
+[![CI](https://github.com/zanni098/DuckTap/actions/workflows/ci.yml/badge.svg)](https://github.com/zanni098/DuckTap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+DuckTap is inspired by [Printing Press](https://printingpress.dev) by
+[@mvanhorn](https://github.com/mvanhorn) — same north star (*muscle memory for
+agents*) — rebuilt in Python with multi-LLM support, a web dashboard,
+Playwright-powered browser sniffing, and a real plugin system.
+
+## Why a CLI factory?
+
+In a world of AI agents, **a well-designed CLI is muscle memory**. No hunting
+through docs, no wrong turns, no wasted tokens. DuckTap reads the spec, sniffs
+the traffic when no spec exists, and prints:
+
+- **A Python CLI** (`<api>-dt-cli`) — Click-based, auth from env vars, JSON by default, pretty mode for humans, local SQLite mirror for compound queries, retries on transient errors.
+- **An MCP server** (`<api>-dt-mcp`) — every operation exposed as an MCP tool, stdio transport, drop into Claude Desktop or Cursor in 60 seconds.
+- **A skill** for Claude Code, Cursor (`.mdc`), and a generic `tools.json` — so any agent harness can pick up where the others left off.
+- **A scorecard** grading coverage, docs, auth clarity, typed params, artifacts, and naming.
+
+## Install
+
+```bash
+git clone https://github.com/zanni098/DuckTap
+cd ducktap
+pip install -e ".[dev]"
+ducktap --version
+```
+
+For browser sniffing:
+
+```bash
+pip install -e ".[dev,sniff]"
+playwright install chromium
+```
+
+## Quick start
+
+```bash
+# 1. From an OpenAPI spec (file or URL)
+ducktap press https://petstore3.swagger.io/api/v3/openapi.yaml
+
+# 2. From a HAR file (recorded browser traffic)
+ducktap press ./capture.har --name myapi
+
+# 3. From a website with no public spec
+ducktap sniff https://example.com
+
+# 4. From the curated catalog
+ducktap catalog list
+ducktap catalog print stripe
+
+# 5. Browse + drive everything from the dashboard
+ducktap ui    # http://127.0.0.1:8765
+```
+
+What you get under `./out/`:
+
+```
+out/
+├── petstore-dt-cli/        # pip install -e .  →  petstore-dt-cli --help
+│   ├── pyproject.toml
+│   ├── README.md
+│   ├── petstore_dt_cli/
+│   │   ├── main.py
+│   │   ├── commands.py     # one click subcommand per API operation
+│   │   ├── client.py       # httpx + env-var auth + retries
+│   │   └── mirror.py       # local SQLite cache
+│   └── tests/test_smoke.py
+├── petstore-dt-mcp/        # pip install -e .  →  add to Claude Desktop config
+│   └── petstore_dt_mcp/server.py
+└── skills/ducktap-petstore/
+    ├── SKILL.md            # Claude Code skill
+    ├── ducktap-petstore.mdc  # Cursor rule
+    └── tools.json          # generic agent tool definitions
+```
+
+## How DuckTap improves on Printing Press
+
+| | Printing Press | **DuckTap** |
+|---|---|---|
+| Language | Go | Python — easier to extend, richer LLM ecosystem |
+| LLM | Claude only | **Multi-LLM via LiteLLM** (Anthropic, OpenAI, Gemini, Ollama, Groq, Azure) |
+| Skills | Claude Code | **Claude Code + Cursor `.mdc` + generic `tools.json`** |
+| UI | None | **Local FastAPI dashboard** (`ducktap ui`) |
+| Plugins | Source fork | **Entry-point plugin system** — drop-in discoverers & generators |
+| Browser sniff | Custom Go browser | **Playwright** — full HAR export, scriptable actions |
+| Generated CLI runtime | Single Go binary | Python (pip-installable, hackable, single-file editable) |
+
+See [`docs/COMPARISON.md`](docs/COMPARISON.md) for the full feature matrix.
+
+## Commands
+
+```text
+ducktap press <source>          # discover + generate (the default loop)
+ducktap research <source>       # discover only — emit normalized APISpec JSON
+ducktap sniff <url>             # browser-sniff a site (needs [sniff] extra)
+ducktap scorecard <source>      # quality scorecard
+ducktap shipcheck <name>        # structural & runtime sanity checks
+ducktap catalog list|print      # browse the recipe library
+ducktap plugins list            # show installed discoverers + generators
+ducktap ui                      # local web dashboard
+```
+
+## Plugins
+
+Add a discoverer or generator without forking. Register via Python entry points:
+
+```toml
+# your_plugin/pyproject.toml
+[project.entry-points."ducktap.plugins"]
+mything = "your_plugin.module"   # module just calls plugins.register_discoverer(...)
+```
+
+See [`docs/PLUGINS.md`](docs/PLUGINS.md) and the sample at
+`src/ducktap/plugins/builtin/graphql_intro.py`.
+
+## Architecture
+
+```
+input (URL | spec | HAR)
+        │
+        ▼
+  ┌─────────────┐
+  │  Discovery  │   openapi / har / browser-sniff / graphql (plugin) / …
+  └──────┬──────┘
+         ▼
+   APISpec (Pydantic) ──── intermediate normalized representation
+         │
+         ▼
+  ┌─────────────┐
+  │  Generator  │   python-cli / mcp-server / skill / …
+  └──────┬──────┘
+         ▼
+  artifacts/       (CLI pkg + MCP pkg + SKILL.md + cursor.mdc + tools.json)
+         │
+         ▼
+  ┌─────────────┐
+  │   Verify    │   scorecard + shipcheck + (optional) live smoke test
+  └─────────────┘
+```
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Roadmap
+
+See [`docs/ROADMAP.md`](docs/ROADMAP.md). Highlights for v0.2+:
+
+- LLM-assisted **polish** step (operation descriptions, command names, doc strings)
+- **GraphQL** first-class (today: plugin, beta)
+- **Auth doctor** — detect login flows during sniffing, emit accurate auth blocks
+- **Compound query** macros (canonical "what's interesting about X" recipes)
+- **CLI publish** to PyPI + GitHub in one command
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgements
+
+Inspired by [Printing Press](https://github.com/mvanhorn/cli-printing-press) by
+Matt Van Horn and the agent-CLI playbook proved out by
+[discrawl](https://github.com/steipete/discrawl) and
+[gogcli](https://github.com/steipete/gogcli).

ducktap-0.1.0/README.md

@@ -0,0 +1,171 @@
+# DuckTap
+
+> **Tape any API to your agent in one command.**
+> DuckTap is a CLI factory for AI agents. Point it at an OpenAPI spec, a HAR
+> file, or a plain website, and it *prints* a Python CLI, an MCP server, and a
+> Claude/Cursor/Codex skill — wired up, cached, scored, ready to ship.
+
+[![CI](https://github.com/zanni098/DuckTap/actions/workflows/ci.yml/badge.svg)](https://github.com/zanni098/DuckTap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+DuckTap is inspired by [Printing Press](https://printingpress.dev) by
+[@mvanhorn](https://github.com/mvanhorn) — same north star (*muscle memory for
+agents*) — rebuilt in Python with multi-LLM support, a web dashboard,
+Playwright-powered browser sniffing, and a real plugin system.
+
+## Why a CLI factory?
+
+In a world of AI agents, **a well-designed CLI is muscle memory**. No hunting
+through docs, no wrong turns, no wasted tokens. DuckTap reads the spec, sniffs
+the traffic when no spec exists, and prints:
+
+- **A Python CLI** (`<api>-dt-cli`) — Click-based, auth from env vars, JSON by default, pretty mode for humans, local SQLite mirror for compound queries, retries on transient errors.
+- **An MCP server** (`<api>-dt-mcp`) — every operation exposed as an MCP tool, stdio transport, drop into Claude Desktop or Cursor in 60 seconds.
+- **A skill** for Claude Code, Cursor (`.mdc`), and a generic `tools.json` — so any agent harness can pick up where the others left off.
+- **A scorecard** grading coverage, docs, auth clarity, typed params, artifacts, and naming.
+
+## Install
+
+```bash
+git clone https://github.com/zanni098/DuckTap
+cd ducktap
+pip install -e ".[dev]"
+ducktap --version
+```
+
+For browser sniffing:
+
+```bash
+pip install -e ".[dev,sniff]"
+playwright install chromium
+```
+
+## Quick start
+
+```bash
+# 1. From an OpenAPI spec (file or URL)
+ducktap press https://petstore3.swagger.io/api/v3/openapi.yaml
+
+# 2. From a HAR file (recorded browser traffic)
+ducktap press ./capture.har --name myapi
+
+# 3. From a website with no public spec
+ducktap sniff https://example.com
+
+# 4. From the curated catalog
+ducktap catalog list
+ducktap catalog print stripe
+
+# 5. Browse + drive everything from the dashboard
+ducktap ui    # http://127.0.0.1:8765
+```
+
+What you get under `./out/`:
+
+```
+out/
+├── petstore-dt-cli/        # pip install -e .  →  petstore-dt-cli --help
+│   ├── pyproject.toml
+│   ├── README.md
+│   ├── petstore_dt_cli/
+│   │   ├── main.py
+│   │   ├── commands.py     # one click subcommand per API operation
+│   │   ├── client.py       # httpx + env-var auth + retries
+│   │   └── mirror.py       # local SQLite cache
+│   └── tests/test_smoke.py
+├── petstore-dt-mcp/        # pip install -e .  →  add to Claude Desktop config
+│   └── petstore_dt_mcp/server.py
+└── skills/ducktap-petstore/
+    ├── SKILL.md            # Claude Code skill
+    ├── ducktap-petstore.mdc  # Cursor rule
+    └── tools.json          # generic agent tool definitions
+```
+
+## How DuckTap improves on Printing Press
+
+| | Printing Press | **DuckTap** |
+|---|---|---|
+| Language | Go | Python — easier to extend, richer LLM ecosystem |
+| LLM | Claude only | **Multi-LLM via LiteLLM** (Anthropic, OpenAI, Gemini, Ollama, Groq, Azure) |
+| Skills | Claude Code | **Claude Code + Cursor `.mdc` + generic `tools.json`** |
+| UI | None | **Local FastAPI dashboard** (`ducktap ui`) |
+| Plugins | Source fork | **Entry-point plugin system** — drop-in discoverers & generators |
+| Browser sniff | Custom Go browser | **Playwright** — full HAR export, scriptable actions |
+| Generated CLI runtime | Single Go binary | Python (pip-installable, hackable, single-file editable) |
+
+See [`docs/COMPARISON.md`](docs/COMPARISON.md) for the full feature matrix.
+
+## Commands
+
+```text
+ducktap press <source>          # discover + generate (the default loop)
+ducktap research <source>       # discover only — emit normalized APISpec JSON
+ducktap sniff <url>             # browser-sniff a site (needs [sniff] extra)
+ducktap scorecard <source>      # quality scorecard
+ducktap shipcheck <name>        # structural & runtime sanity checks
+ducktap catalog list|print      # browse the recipe library
+ducktap plugins list            # show installed discoverers + generators
+ducktap ui                      # local web dashboard
+```
+
+## Plugins
+
+Add a discoverer or generator without forking. Register via Python entry points:
+
+```toml
+# your_plugin/pyproject.toml
+[project.entry-points."ducktap.plugins"]
+mything = "your_plugin.module"   # module just calls plugins.register_discoverer(...)
+```
+
+See [`docs/PLUGINS.md`](docs/PLUGINS.md) and the sample at
+`src/ducktap/plugins/builtin/graphql_intro.py`.
+
+## Architecture
+
+```
+input (URL | spec | HAR)
+        │
+        ▼
+  ┌─────────────┐
+  │  Discovery  │   openapi / har / browser-sniff / graphql (plugin) / …
+  └──────┬──────┘
+         ▼
+   APISpec (Pydantic) ──── intermediate normalized representation
+         │
+         ▼
+  ┌─────────────┐
+  │  Generator  │   python-cli / mcp-server / skill / …
+  └──────┬──────┘
+         ▼
+  artifacts/       (CLI pkg + MCP pkg + SKILL.md + cursor.mdc + tools.json)
+         │
+         ▼
+  ┌─────────────┐
+  │   Verify    │   scorecard + shipcheck + (optional) live smoke test
+  └─────────────┘
+```
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Roadmap
+
+See [`docs/ROADMAP.md`](docs/ROADMAP.md). Highlights for v0.2+:
+
+- LLM-assisted **polish** step (operation descriptions, command names, doc strings)
+- **GraphQL** first-class (today: plugin, beta)
+- **Auth doctor** — detect login flows during sniffing, emit accurate auth blocks
+- **Compound query** macros (canonical "what's interesting about X" recipes)
+- **CLI publish** to PyPI + GitHub in one command
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgements
+
+Inspired by [Printing Press](https://github.com/mvanhorn/cli-printing-press) by
+Matt Van Horn and the agent-CLI playbook proved out by
+[discrawl](https://github.com/steipete/discrawl) and
+[gogcli](https://github.com/steipete/gogcli).

ducktap-0.1.0/catalog/github.yaml

@@ -0,0 +1,9 @@
+name: github
+display_name: GitHub REST
+description: Full GitHub REST v3 API surface — repos, issues, PRs, actions, search.
+category: developer
+spec_url: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
+spec_format: json
+tier: official
+homepage: https://docs.github.com/rest
+notes: Large spec (~1000 endpoints). Use `--targets python-cli` to skip MCP if tools list is too long for your harness.

ducktap-0.1.0/catalog/petstore.yaml

@@ -0,0 +1,9 @@
+name: petstore
+display_name: Swagger Petstore
+description: Canonical OpenAPI example — pet store management.
+category: example
+spec_url: https://petstore3.swagger.io/api/v3/openapi.yaml
+spec_format: yaml
+tier: official
+homepage: https://petstore3.swagger.io
+notes: Used as DuckTap's smoke test.

ducktap-0.1.0/catalog/stripe.yaml

@@ -0,0 +1,8 @@
+name: stripe
+display_name: Stripe API
+description: Payments, customers, subscriptions, invoices, products, prices.
+category: payments
+spec_url: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
+spec_format: json
+tier: official
+homepage: https://stripe.com/docs/api

ducktap-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,48 @@
+# DuckTap Architecture
+
+DuckTap is organized around one normalized data model (`APISpec`) sitting
+between two extensible plugin layers (Discoverers and Generators).
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `ducktap.core.spec` | `APISpec` (pydantic) — the intermediate representation. |
+| `ducktap.core.naming` | Slugify, snake/kebab case, flag/env-var conventions. |
+| `ducktap.core.plugins` | Plugin registry + entry-point loader. |
+| `ducktap.core.pipeline` | High-level `discover()` and `press()`. |
+| `ducktap.discovery.openapi` | OpenAPI 2/3 → `APISpec`. |
+| `ducktap.discovery.har` | HAR file → `APISpec` (clustered request grouping). |
+| `ducktap.discovery.browser_sniff` | Playwright → HAR → `APISpec`. |
+| `ducktap.generator.python_cli` | `APISpec` → Click-based Python CLI package. |
+| `ducktap.generator.mcp_server` | `APISpec` → MCP server package (stdio). |
+| `ducktap.generator.skill` | `APISpec` → `SKILL.md`, `.mdc`, `tools.json`. |
+| `ducktap.llm.base` | LiteLLM wrapper — multi-provider chat. |
+| `ducktap.verify.scorecard` | Quality grading (6 dimensions). |
+| `ducktap.verify.shipcheck` | Structural + runtime sanity checks. |
+| `ducktap.catalog.registry` | YAML recipe loader. |
+| `ducktap.webui.app` | FastAPI dashboard. |
+| `ducktap.cli` | Top-level `ducktap` Typer entry point. |
+
+## The pipeline
+
+```
+press(source, out_dir)
+  │
+  ├── discover(source)
+  │     for d in [openapi, har, browser-sniff, …]:
+  │       if d.can_handle(source): return d.discover(source)
+  │
+  ├── for tgt in targets:
+  │     generators[tgt].generate(spec, out_dir)
+  │
+  └── PressResult(spec, out_dir, artifacts)
+```
+
+## Why this shape
+
+- **One intermediate format** means new discoverers and new generators evolve independently.
+- **Plugins via entry points** means improvements ship as PyPI packages, not forks.
+- **Pydantic models** give us free JSON serialization (research command writes the spec to disk for inspection / debugging / LLM polish steps).
+- **Click for generated CLIs** because every Python user already has it and Click subcommands have richer help output than argparse out of the box.
+- **MCP SDK** rather than hand-rolled JSON-RPC, so we get protocol-version updates for free.