feat: pip-install quickstart with bundled --example + 3-path getting-started

[changliu2]

What

Make pip install assert-ai the canonical install and give every onboarding shape a pip-only, zero-clone runnable path. Replaces the editable git clone + pip install -e ".[otel,langgraph]" quickstart, which was heavy boilerplate, invisible to PyPI download telemetry, and didn't match the published assert-ai package.

Three quickstart paths

The README, docs/getting-started.md, and the website now lead with pip install assert-ai and branch into three paths that map to how the user arrives:

Tab	For	Install
I have an agent	LangGraph / CrewAI / OpenAI Agents SDK / custom	pip install "assert-ai[otel]" — connect via the auto_trace 2-liner + target.callable
I have the agent spec	a system prompt / description	pip install assert-ai → assert-ai run --example health-assistant
Help me start	nothing yet	pip install assert-ai → assert-ai init

Bundled examples (--example)

• New assert_ai/_examples/ subpackage ships two runnable configs in the wheel (configs + agent code only — no result artifacts):
  • health-assistant — Prompt Agent (system_prompt); runs on a base install
  • travel-planner-langgraph — LangGraph + OpenTelemetry trace capture; needs [langgraph,otel]
• assert-ai run --example <name> resolves the bundled config. No value (or an unknown name) lists the catalog with per-example install hints. --config and --example are mutually exclusive.
• Wheel stays 0.31 MB; verified a clean-venv install resolves --example from site-packages.

Website

• Real <QuickstartTabs> client component (3 tabs + macOS/Linux ↔ Windows sub-toggle), injected by MarkdownContent via a <!--quickstart-tabs--> sentinel in docs/getting-started.md. GitHub renders the same three paths as a Markdown fallback (sentinels are invisible there).
• Fixed a stale microsoft/ASSERT docs blob URL → responsibleai/ASSERT.

Notes

• Extras are always quoted ("assert-ai[otel]") so zsh / PowerShell don't glob the brackets.
• AGENTS.md setup commands updated to the published-package path with explicit per-scenario extras.
• A follow-up PR removes the ~19 MB of committed examples/incident_triage_agent/artifacts/*.jsonl and gitignores result artifacts (kept separate to keep this diff reviewable).

Test plan

• 7 new CLI/registry tests (tests/test_cli.py) pass
• python -m build → wheel ships both configs, zero artifacts leaked
• clean-venv pip install <wheel> → assert-ai run --example resolves from site-packages
• website tsc --noEmit + eslint + next build all pass (/docs/getting-started prerenders)
• pre-existing test_viewer_* failures confirmed present on main (Node/TS env, unrelated)

[jakepresent]

Requesting changes. The direction is good, but I found two issues that hit the new public quickstart surface directly.

1. assert-ai run --example without a value does not work with the supported Click dependency range. The PR body, help text, and test say that --example with no value should list the catalog, but with Click 8.3.1 I get:

Error: Option '--example' requires an argument.

I reproduced it by running python -m pytest tests/test_cli.py -q; CliTest.test_example_without_value_lists_catalog fails. Since pyproject.toml allows click>=8.0, a fresh pip install assert-ai can resolve to this version, so the advertised no-value form is not safe. Either make that form actually work across the allowed Click versions, or change the CLI/docs to use an explicit catalog command/form instead.

2. The pip-only docs still tell users to copy .env.example, but zero-clone users will not have that file. docs/getting-started.md and the website quickstart tabs show cp .env.example .env / Copy-Item .env.example .env immediately after pip install assert-ai. In a clean pip-only directory there is no .env.example, so the first-run path fails before ASSERT runs. For the zero-clone path, use direct environment-variable instructions or a command that creates a minimal .env with placeholders.

I stopped there because both are user-facing onboarding blockers for the exact surface this PR is changing.

[changliu2]

Thanks @jakepresent — both were real onboarding blockers on the exact surface this PR changes. Fixed in ca67d8c.

1. --example without a value broke on Click 8.3.1.
You're right — the flag_value trick wasn't safe across click>=8.0. Removed it: --example is now a plain value-taking option, and the catalog is discoverable via a new assert-ai examples command that works across the supported Click range. The unknown-name and no---config/no---example paths still print the catalog. Replaced the test_example_without_value_lists_catalog test with test_examples_command_lists_catalog + test_bare_example_flag_errors; pytest tests/test_cli.py is green (16 passed).

2. .env.example doesn't exist for pip-only users.
Correct — after a bare pip install assert-ai there's no .env.example to copy. The three pip-only paths now say: set AZURE_API_KEY / AZURE_API_BASE as env vars, or create a .env in the working dir — which the runner already auto-loads via find_dotenv(usecwd=True) (runner.py:63), so a hand-created .env works zero-clone. The clone-based "develop from source" path keeps cp .env.example .env. Fixed in docs/getting-started.md (3 tabs) and the website QuickstartTabs (the bash/PowerShell envLine).

Re-requesting review. Thanks for catching both before they hit users. 🙏

[tangym]

Agree pip-first is the right call. One concern: PyPI is published from GitHub releases, so the wheel will lag main between releases, and we don't have a release cadence yet, so a doc on main referencing a not-yet-released feature will make pip look broken. Could we either agree on a cadence (even loose, e.g. tag on user-visible features) or keep a short "want the latest from main?" pointer to the source install next to the pip command until cadence is settled? Also please rebase, currently conflicting with main.

[changliu2]

Rebased onto main and re-verified both of Jake's fixes hold (bare --example now errors cleanly via the new examples command, zero-clone quickstart no longer references .env.example).

On the cadence question — added a one-line pointer in "Develop from source" calling it out explicitly as the path for "just landed on main, not on PyPI yet" (62c8363). I've asked Aaron to work out an actual release-cadence proposal separately, so that doesn't need to hold up this PR.

[changliu2]

@jakepresent pushed fixes for both issues -- bare --example now surfaces the catalog via a dedicated assert-ai examples command (Click can't make the bare-flag form work cleanly across the supported version range, so this is the alternative you offered), and the zero-clone quickstart no longer references .env.example. Rebased onto main, 19/19 CLI tests pass. Mind re-reviewing when you get a chance?

[AaronAspinwall123]

@changliu2 closing for hygiene. Please reopen if needed.