walla-cli 0.1.0__tar.gz

walla_cli-0.1.0/.cursor/rules/quality.mdc

@@ -0,0 +1,14 @@
+---
+description: Extreme quality bar for walla (Korotkevich + Gray)
+alwaysApply: true
+---
+
+Before editing `walla/`, read:
+
+- `docs/code_quality.md` (Korotkevich / Tourist bar)
+- `docs/data_engineering_standards.md` (Gray / Stonebraker bar)
+- `docs/WIRE.md`
+
+Enforce: downward DAG, <=250 LOC/file, no import side effects, `mypy --strict`,
+no password/token in logs, fixture + parser test for wire changes.
+Run `python scripts/check_code_quality.py` and `pytest -q -m "not live"`.

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

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          pip install -e ".[dev,mcp]"
+      - name: Quality
+        run: |
+          python scripts/check_code_quality.py
+          ruff check .
+          mypy walla scripts/check_code_quality.py
+      - name: Tests
+        run: pytest -q -m "not live" --cov=walla --cov-fail-under=90

walla_cli-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.env
+.env.*
+*.pyc
+__pycache__/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+session.json
+**/session.json
+cookies.json
+cookies.txt
+*.cookies
+.DS_Store

walla_cli-0.1.0/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md — how to extend `walla`
+
+You are working on **walla**: Wallapop.es CLI / library / MCP (look · offer · talk).
+
+## Quality (read first)
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar
+- [`docs/WIRE.md`](docs/WIRE.md) — captured wire
+- [`docs/objective_function.md`](docs/objective_function.md)
+
+Run before shipping:
+
+```bash
+python scripts/check_code_quality.py
+ruff check .
+mypy walla
+pytest -q -m "not live"
+```
+
+## Calling walla from an agent
+
+```bash
+pipx install 'walla-cli[mcp]'
+walla instruct --json
+walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --json
+walla login --cookie '<session-token>' --json
+walla search "tabla" --json
+```
+
+Never print session cookies or bearer tokens. On `error_type: auth`, ask the human
+to run `walla login` and paste `__Secure-next-auth.session-token`.
+
+## Architecture map
+
+| Path | Owns | Must not |
+|------|------|----------|
+| `walla/models/` | Pydantic DTOs | I/O |
+| `walla/http/` | curl_cffi, polite | CLI/MCP imports |
+| `walla/core/` | Envelope, errors, paths, human_fix | Live Wallapop calls (except doctor via CLI) |
+| `walla/search/` | Public look | Account mutations |
+| `walla/account/` | Session, inbox, say, offer, fav | HTML scrape |
+| `walla/hunter/` | Profile, watches, GRAB/LOOK/PASS | HTTP |
+| `walla/cli/` | Typer + Rich + `--json` | Import MCP |
+| `walla/mcp/` | FastMCP | Import CLI |
+
+Ranks: models 10 → exceptions 15 → http 20 → core 30 → search/account/hunter 40 → cli/mcp 50.
+
+## Live capture workflow
+
+1. Reproduce in browser Network on `es.wallapop.com`.
+2. Call with `curl_cffi` + `X-DeviceOS: 0`.
+3. Redact secrets → `fixtures/` → parser test → update `docs/WIRE.md`.
+4. Never HTML-scrape as the primary path. Never Playwright.
+
+## Do / don't
+
+- **Do** keep files <= 250 LOC.
+- **Do** fail closed; typed `error_type`.
+- **Do** require `--yes` for say/offer.
+- **Don't** commit session.json, cookies, or tokens.
+- **Don't** invent wire shapes without a fixture.
+- **Don't** require `.env` credentials; login is cookie paste.

walla_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Berend Gort
+
+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.

walla_cli-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: walla-cli
+Version: 0.1.0
+Summary: Wallapop.es CLI - look · offer · talk for humans and agents
+Project-URL: Homepage, https://github.com/berendgort/wallapop-cli
+Project-URL: Repository, https://github.com/berendgort/wallapop-cli
+Project-URL: Issues, https://github.com/berendgort/wallapop-cli/issues
+Author-email: "Dr. Berend Gort" <berend.gort@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,marketplace,mcp,spain,wallapop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: rich>=13.8.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: typer>=0.15.1
+Provides-Extra: all
+Requires-Dist: build>=1.2.0; extra == 'all'
+Requires-Dist: fastmcp>=3.2; extra == 'all'
+Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: mypy>=1.14.0; extra == 'all'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'all'
+Requires-Dist: pytest>=8.3.4; extra == 'all'
+Requires-Dist: ruff>=0.8.4; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.8.4; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.2; extra == 'mcp'
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# walla
+
+```
+██╗    ██╗  █████╗  ██╗      ██╗       █████╗            ██████╗ ██╗      ██╗
+██║    ██║ ██╔══██╗ ██║      ██║      ██╔══██╗          ██╔════╝ ██║      ██║
+██║ █╗ ██║ ███████║ ██║      ██║      ███████║  █████╗  ██║      ██║      ██║
+██║███╗██║ ██╔══██║ ██║      ██║      ██╔══██║  ╚════╝  ██║      ██║      ██║
+╚███╔███╔╝ ██║  ██║ ███████╗ ███████╗ ██║  ██║          ╚██████╗ ███████╗ ██║
+ ╚══╝╚══╝  ╚═╝  ╚═╝ ╚══════╝ ╚══════╝ ╚═╝  ╚═╝           ╚═════╝ ╚══════╝ ╚═╝
+  look · offer · talk
+  Dr. Berend Gort  ·  www.berendgort.dev
+```
+
+![walla banner](docs/assets/walla-github-banner.jpg)
+
+**walla** is an unofficial Wallapop.es **CLI + MCP + Python library** for Cursor
+agents and humans: search listings, read inbox, send a message, make an offer.
+
+Not affiliated with Wallapop. Respect ToS and rate limits.
+
+### What this unlocks
+
+You tell Cursor: *“Find me a used kite near Barcelona under €400, message
+the seller, and offer if it’s a GRAB.”*
+
+The agent runs `walla` — ranks listings **GRAB / LOOK / PASS**, links you the
+item, asks before sending, then talks and offers on your behalf:
+
+```bash
+walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --budget 400
+walla search "tabla kite Cabrinha" --max 40 --json
+# agent: GRAB · Cabrinha Moto 10m · €320 · 4 km
+#        https://es.wallapop.com/item/...
+
+walla login                         # paste session cookie once
+walla say <id> "Hola, ¿sigue disponible? Puedo pasar hoy." --yes
+walla offer <id> --eur 280 --yes    # prints total; needs your confirm
+walla inbox --json                  # catch the reply
+```
+
+That is the product: a Cursor agent that can **look, talk, and offer** on
+Wallapop without opening the website for every step.
+
+**Quality bar (enforced in CI):**
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar
+- [`docs/WIRE.md`](docs/WIRE.md) — captured consumer API
+- [`docs/rate_limit_analysis.md`](docs/rate_limit_analysis.md) — polite spacing
+
+---
+
+## For AI agents (mandatory protocol)
+
+If the user pasted this GitHub link (or this README), **follow this section exactly**.
+
+### Goal
+
+Look, offer, and talk on wallapop.es using the `walla` package. Speak briefly.
+Link listings as `https://es.wallapop.com/item/<web_slug>`. Verdicts:
+**GRAB / LOOK / PASS**.
+
+### Bootstrap
+
+1. Install from this clone:
+   ```bash
+pipx install 'walla-cli[mcp]'
+# from clone: pipx install -e '.[mcp]'
+```
+2. `walla doctor --json` — read `auth.session` and `network.reachable`.
+   **Never** print tokens or cookies.
+3. If no session: ask the human to run `walla login` and paste
+   `__Secure-next-auth.session-token` from es.wallapop.com (Cookie-Editor).
+   Agents may pass it non-interactively: `walla login --cookie '<value>' --json`.
+4. Do the ask with `walla … --json` and narrate in prose.
+
+Optional MCP:
+
+```json
+{
+  "mcpServers": {
+    "walla": { "command": "walla-mcp" }
+  }
+}
+```
+
+### Operating loop
+
+| Ask | Command |
+|-----|---------|
+| Look | `walla search "tabla kite" --max 40 --json` then `walla item <id> --json` |
+| Talk | `walla inbox --json` · `walla thread <id> --json` · `walla say <id> "…" --yes` |
+| Offer | `walla offer <id> --eur 180 --yes` |
+
+Rules:
+
+- Reads are safe. `say` / `offer` need `--yes` / `confirm=true`. Name listing + euros.
+- If they only asked to look, do not send.
+- Ambiguous match: ask once with candidates.
+- In-person offers outside pickup radius: refuse.
+- Envelope: `ok`, `api_version`, `data` or `error` / `error_type` / `retryable`.
+
+`walla instruct --json` returns this recipe.
+
+---
+
+## Install
+
+```bash
+git clone git@github.com:berendgort/wallapop-cli.git
+cd wallapop-cli
+pipx install 'walla-cli[mcp]'   # or: pipx install -e '.[mcp]'
+walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --json
+walla login          # paste __Secure-next-auth.session-token
+walla doctor --json
+```
+
+## CLI
+
+| Command | Role |
+|---------|------|
+| `walla setup` / `profile` | Home point, radius, budget |
+| `walla search` / `item` / `categories` | Look |
+| `walla watch add\|list\|check` | Local saved searches |
+| `walla login` / `logout` / `whoami` | Session (paste cookie; optional `--password`) |
+| `walla inbox` / `thread` / `say` | Talk |
+| `walla offer` | Offer (prints total, needs `--yes`) |
+| `walla fav list\|add\|rm` | Favorites |
+| `walla instruct` / `doctor` | Agent recipe + health |
+
+## Develop
+
+```bash
+pip install -e '.[dev,mcp]'
+pytest -q -m 'not live'
+pytest -m live          # hits Wallapop; needs network
+ruff check .
+mypy walla
+python scripts/check_code_quality.py
+```
+
+| Layer | Path | Role |
+|-------|------|------|
+| Models | `walla/models/` | Pydantic only |
+| HTTP | `walla/http/` | curl_cffi + polite |
+| Core | `walla/core/` | Envelope, errors, human_fix |
+| Search | `walla/search/` | Look |
+| Account | `walla/account/` | Session, inbox, offer |
+| Hunter | `walla/hunter/` | Profile, watches, verdicts |
+| CLI / MCP | `walla/cli/` · `walla/mcp/` | Entrypoints |
+
+Read [`AGENTS.md`](AGENTS.md) before extending.
+
+## Disclaimer
+
+Unofficial. Not affiliated with Wallapop. Personal / research use.
+
+## License
+
+MIT

walla_cli-0.1.0/README.md

@@ -0,0 +1,160 @@
+# walla
+
+```
+██╗    ██╗  █████╗  ██╗      ██╗       █████╗            ██████╗ ██╗      ██╗
+██║    ██║ ██╔══██╗ ██║      ██║      ██╔══██╗          ██╔════╝ ██║      ██║
+██║ █╗ ██║ ███████║ ██║      ██║      ███████║  █████╗  ██║      ██║      ██║
+██║███╗██║ ██╔══██║ ██║      ██║      ██╔══██║  ╚════╝  ██║      ██║      ██║
+╚███╔███╔╝ ██║  ██║ ███████╗ ███████╗ ██║  ██║          ╚██████╗ ███████╗ ██║
+ ╚══╝╚══╝  ╚═╝  ╚═╝ ╚══════╝ ╚══════╝ ╚═╝  ╚═╝           ╚═════╝ ╚══════╝ ╚═╝
+  look · offer · talk
+  Dr. Berend Gort  ·  www.berendgort.dev
+```
+
+![walla banner](docs/assets/walla-github-banner.jpg)
+
+**walla** is an unofficial Wallapop.es **CLI + MCP + Python library** for Cursor
+agents and humans: search listings, read inbox, send a message, make an offer.
+
+Not affiliated with Wallapop. Respect ToS and rate limits.
+
+### What this unlocks
+
+You tell Cursor: *“Find me a used kite near Barcelona under €400, message
+the seller, and offer if it’s a GRAB.”*
+
+The agent runs `walla` — ranks listings **GRAB / LOOK / PASS**, links you the
+item, asks before sending, then talks and offers on your behalf:
+
+```bash
+walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --budget 400
+walla search "tabla kite Cabrinha" --max 40 --json
+# agent: GRAB · Cabrinha Moto 10m · €320 · 4 km
+#        https://es.wallapop.com/item/...
+
+walla login                         # paste session cookie once
+walla say <id> "Hola, ¿sigue disponible? Puedo pasar hoy." --yes
+walla offer <id> --eur 280 --yes    # prints total; needs your confirm
+walla inbox --json                  # catch the reply
+```
+
+That is the product: a Cursor agent that can **look, talk, and offer** on
+Wallapop without opening the website for every step.
+
+**Quality bar (enforced in CI):**
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar
+- [`docs/WIRE.md`](docs/WIRE.md) — captured consumer API
+- [`docs/rate_limit_analysis.md`](docs/rate_limit_analysis.md) — polite spacing
+
+---
+
+## For AI agents (mandatory protocol)
+
+If the user pasted this GitHub link (or this README), **follow this section exactly**.
+
+### Goal
+
+Look, offer, and talk on wallapop.es using the `walla` package. Speak briefly.
+Link listings as `https://es.wallapop.com/item/<web_slug>`. Verdicts:
+**GRAB / LOOK / PASS**.
+
+### Bootstrap
+
+1. Install from this clone:
+   ```bash
+pipx install 'walla-cli[mcp]'
+# from clone: pipx install -e '.[mcp]'
+```
+2. `walla doctor --json` — read `auth.session` and `network.reachable`.
+   **Never** print tokens or cookies.
+3. If no session: ask the human to run `walla login` and paste
+   `__Secure-next-auth.session-token` from es.wallapop.com (Cookie-Editor).
+   Agents may pass it non-interactively: `walla login --cookie '<value>' --json`.
+4. Do the ask with `walla … --json` and narrate in prose.
+
+Optional MCP:
+
+```json
+{
+  "mcpServers": {
+    "walla": { "command": "walla-mcp" }
+  }
+}
+```
+
+### Operating loop
+
+| Ask | Command |
+|-----|---------|
+| Look | `walla search "tabla kite" --max 40 --json` then `walla item <id> --json` |
+| Talk | `walla inbox --json` · `walla thread <id> --json` · `walla say <id> "…" --yes` |
+| Offer | `walla offer <id> --eur 180 --yes` |
+
+Rules:
+
+- Reads are safe. `say` / `offer` need `--yes` / `confirm=true`. Name listing + euros.
+- If they only asked to look, do not send.
+- Ambiguous match: ask once with candidates.
+- In-person offers outside pickup radius: refuse.
+- Envelope: `ok`, `api_version`, `data` or `error` / `error_type` / `retryable`.
+
+`walla instruct --json` returns this recipe.
+
+---
+
+## Install
+
+```bash
+git clone git@github.com:berendgort/wallapop-cli.git
+cd wallapop-cli
+pipx install 'walla-cli[mcp]'   # or: pipx install -e '.[mcp]'
+walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --json
+walla login          # paste __Secure-next-auth.session-token
+walla doctor --json
+```
+
+## CLI
+
+| Command | Role |
+|---------|------|
+| `walla setup` / `profile` | Home point, radius, budget |
+| `walla search` / `item` / `categories` | Look |
+| `walla watch add\|list\|check` | Local saved searches |
+| `walla login` / `logout` / `whoami` | Session (paste cookie; optional `--password`) |
+| `walla inbox` / `thread` / `say` | Talk |
+| `walla offer` | Offer (prints total, needs `--yes`) |
+| `walla fav list\|add\|rm` | Favorites |
+| `walla instruct` / `doctor` | Agent recipe + health |
+
+## Develop
+
+```bash
+pip install -e '.[dev,mcp]'
+pytest -q -m 'not live'
+pytest -m live          # hits Wallapop; needs network
+ruff check .
+mypy walla
+python scripts/check_code_quality.py
+```
+
+| Layer | Path | Role |
+|-------|------|------|
+| Models | `walla/models/` | Pydantic only |
+| HTTP | `walla/http/` | curl_cffi + polite |
+| Core | `walla/core/` | Envelope, errors, human_fix |
+| Search | `walla/search/` | Look |
+| Account | `walla/account/` | Session, inbox, offer |
+| Hunter | `walla/hunter/` | Profile, watches, verdicts |
+| CLI / MCP | `walla/cli/` · `walla/mcp/` | Entrypoints |
+
+Read [`AGENTS.md`](AGENTS.md) before extending.
+
+## Disclaimer
+
+Unofficial. Not affiliated with Wallapop. Personal / research use.
+
+## License
+
+MIT

walla_cli-0.1.0/docs/WIRE.md

@@ -0,0 +1,60 @@
+# Wire capture — Wallapop consumer API
+
+Unofficial. Captured against `es.wallapop.com` / `api.wallapop.com` (2026-10-04).
+Re-verify before trusting after a long gap.
+
+## Headers (public)
+
+Required: `X-DeviceOS: 0`. Browser `User-Agent` + `Origin`/`Referer` of
+`https://es.wallapop.com` work. Do not invent an `X-Signature` for search.
+
+## Search
+
+`GET https://api.wallapop.com/api/v3/search`
+
+Params: `source=search_box`, `keywords`, `latitude`, `longitude`, `order_by`
+(`most_relevance` | `newest` | `closest` | price variants), optional
+`min_sale_price`, `max_sale_price`, `category_id`, `next_page`.
+
+Response: `data.section.payload.items[]` (40/page), `meta.next_page` opaque JWT.
+Item fields include `id`, `title`, `description`, `price.amount`, `web_slug`,
+`location`, `reserved.flag`, `shipping`, `created_at`.
+
+Public URL: `https://es.wallapop.com/item/<web_slug>`.
+
+## Item
+
+`GET https://api.wallapop.com/api/v3/items/{id}` — detail with
+`title.original`, `description.original`, `slug`, `share_url`, `user`, counters.
+
+## Categories
+
+`GET https://api.wallapop.com/api/v3/categories` — top-level tree.
+
+## Auth
+
+`POST https://api.wallapop.com/api/v3/access/login` with
+`{"username","password"}` — live probe returned **HTTP 400 empty body**
+(`x-wallapop-service: auth`) for the configured account. Treat as MFA /
+Keycloak. Fallback: import `__Secure-next-auth.session-token` and mint via
+`GET https://es.wallapop.com/api/auth/session` → `{ token }`.
+
+Refresh: `POST /api/v3/access/refresh` with `{ refresh_token }` when password
+login ever succeeds.
+
+## Messaging / offers (auth)
+
+Reported shapes (confirm with a live token before trusting writes):
+
+- Inbox: `GET /api/v3/conversations`
+- Messages: `GET|POST /api/v3/conversations/{id}/messages`
+- Offers: `POST /api/v3/delivery/buyer/offers`
+- Favorites: `/api/v3/users/me/favorites`, `/api/v3/items/{id}/favorite`
+
+Writes that fail closed as `error_type: unsupported` until fixtures exist.
+
+## Rate limits
+
+Default spacing: `WALLA_MIN_INTERVAL=1.0` s. Honor `Retry-After` on 429.
+Repeated 403 opens a circuit (`WALLA_CIRCUIT_TTL`). See
+[`rate_limit_analysis.md`](rate_limit_analysis.md).

walla_cli-0.1.0/docs/code_quality.md

@@ -0,0 +1,80 @@
+# Engineering Standard: The Korotkevich / Tourist Bar
+
+Every line in `walla` must meet a competitive-programming bar: mathematical
+clarity, modular purity, machine readability. Sprawling monoliths, circular
+imports, hidden I/O on import, and ambiguous contracts are forbidden.
+
+Automated enforcement: `python scripts/check_code_quality.py`
+
+---
+
+## 1. Architectural Layers & Dependency Hierarchy
+
+Strict downward DAG. Lower ranks never import higher ranks. Cycles are fatal.
+
+```
+[10] walla.models          Pydantic DTOs only
+[20] walla.http            curl_cffi client, polite spacing, headers
+[30] walla.core            Envelope, errors, paths, human_fix
+[40] walla.search          Public look (search / item / categories)
+[40] walla.account         Session, inbox, say, offer, favorites
+[40] walla.hunter          Profile, watches, GRAB / LOOK / PASS
+[50] walla.cli · walla.mcp Typer + FastMCP entrypoints
+```
+
+### Invariants
+
+- **Zero Circular Dependencies**: No cycles at module or package level.
+- **Downward Imports Only**: Higher layers may import lower; never reverse
+  (e.g. `search` never imports `cli`, `models` never imports `core`).
+- **Zero Import Side Effects**: No network, disk profile I/O, or client
+  construction on import.
+- **Facades**: Package `__init__.py` files stay thin re-exports.
+- Use `if TYPE_CHECKING:` for type-only upward references.
+
+---
+
+## 2. Hard File Size Cap: <= 250 Lines of Code
+
+No file in `walla/` exceeds **250 lines**. When a module approaches the limit,
+split into single-responsibility submodules behind an `__init__.py` facade.
+
+---
+
+## 3. Functional Core, Imperative Shell
+
+- Pure parsers, verdict math, and cookie parsers take data in and return data out.
+- HTTP, disk session writes, and Typer I/O live in the shell.
+- Fail closed (`ValueError` / typed `WallaError`) on invalid input.
+- Prefer frozen pydantic models for domain transfers.
+
+---
+
+## 4. Credential Zero-Trust
+
+- Never log a bearer access token or the NextAuth session cookie value.
+- Session file (`~/.config/walla/session.json`) is mode `0600`.
+- `doctor` reports `auth.session` as a boolean, never the secret.
+- No `.env` credentials; login is cookie paste (optional password prompt).
+- Redacted fixtures only. No tokens in `fixtures/`.
+
+---
+
+## 5. Machine Readability & Type Enforcement
+
+- `mypy --strict` passes with 0 errors across `walla/`.
+- Every library module defines `__all__`.
+- No unicode em-dash (`\u2014`) or en-dash (`\u2013`) in code or messages.
+- No bare `print()` in application code (CLI banner / catch helpers may write
+  to the Rich console; the quality script allowlists those files).
+
+---
+
+## 6. Verification Commands
+
+```bash
+python scripts/check_code_quality.py
+ruff check .
+mypy walla scripts/check_code_quality.py
+pytest -q -m "not live"
+```