Publish bigquery-agent-analytics-tracing 0.1.0 to PyPI + Claude Code marketplace

Tracking the remaining publish work after the [`tracing-v0.1.0` GitHub release](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/releases/tag/tracing-v0.1.0) cut. Maps to the end of #234 step 4 (PyPI) and #234 step 5 (marketplace).

## State

✅ Done:
- Release tag `tracing-v0.1.0` cut; GitHub release has wheel, sdist, and Claude Code plugin tarball attached.
- `release-tracing.yml` workflow ran: `verify` / `build` / `github-release` all green.

❌ Pending:
- `publish-testpypi` and `publish-pypi` jobs failed on the first run because Trusted Publishers aren't configured yet (expected — see [run #26481268141](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/actions/runs/26481268141)).
- No Claude Code marketplace catalog exists yet, so users have no `/plugin install` path.

## Track 1 — PyPI Trusted Publishing (maintainer action)

Trusted Publisher values (from the OIDC claim set the failed run logged):

| Field | Value |
|---|---|
| Project name | `bigquery-agent-analytics-tracing` |
| Owner | `GoogleCloudPlatform` |
| Repository | `BigQuery-Agent-Analytics-SDK` |
| Workflow filename | `release-tracing.yml` |
| Environment | `testpypi` (TestPyPI) / `pypi` (PyPI) |

Docs: , .

- [ ] **A1.** Create GitHub environment `testpypi` in repo Settings → Environments. No protection rules needed.
- [ ] **A2.** Create GitHub environment `pypi` with **Required reviewers** (at least one maintainer) so every PyPI publish needs a human OK. Recommended: also restrict to **selected tags: `tracing-v*`**.
- [ ] **A3.** Register pending publisher on TestPyPI at with the values above, environment = `testpypi`.
- [ ] **A4.** Register pending publisher on PyPI at with the values above, environment = `pypi`.
- [ ] **A5.** Re-run failed jobs on [the existing release workflow](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/actions/runs/26481268141) — the wheel/sdist artifact is already built and uploaded, no new tag needed. **Caveat:** this only works while the `release-tracing-dist` workflow artifact is still retained (default 90 days, or whatever repo settings dictate). If retention has expired, run the full workflow against the existing tag — `gh workflow run release-tracing.yml --ref tracing-v0.1.0` — to rebuild + re-upload the artifact before the publish jobs can pull it.
- [ ] **A6.** Verify TestPyPI install: `pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ bigquery-agent-analytics-tracing==0.1.0`.
- [ ] **A7.** Verify PyPI install (after the `pypi` environment approval is granted): `pip install bigquery-agent-analytics-tracing==0.1.0`. `python -c \"from bigquery_agent_analytics_tracing import __version__; print(__version__)\"` should print `0.1.0`.

## Track 2 — Claude Code marketplace

**Correction from earlier guidance:** The Claude Code marketplace docs at list supported plugin source types as `relative path`, `github`, `url`, `git-subdir`, and `npm`. There is no `github-release` source type pointing at a release asset tarball. **Do not** point `marketplace.json` directly at the GitHub release tarball — that won't resolve.

Two shapes work. Recommended order: ship **B0** (the in-repo fallback) now to unblock the install path, then move to **B1–B4** (separate distribution repo) once someone with `GoogleCloudPlatform/*` repo-creation rights can set them up.

### B0 — In-repo marketplace catalog (immediate, no new repos needed) — IMPLEMENTED IN #252

Adds the catalog + an expanded dist folder to **this** repo:

```
.claude-plugin/
└── marketplace.json
plugins/
└── claude_code_dist/
└── bigquery-agent-analytics-tracing/
├── .claude-plugin/plugin.json # stamped 0.1.0
├── hooks/
├── commands/
├── scripts/
├── vendor/
├── MARKETPLACE.md
└── README.md
```

`marketplace.json` uses a relative plugin source:

```json
{
"name": "bqaa-tracing",
"owner": { "name": "Google LLC" },
"plugins": [
{
"name": "bigquery-agent-analytics-tracing",
"source": "./plugins/claude_code_dist/bigquery-agent-analytics-tracing",
"description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
"version": "0.1.0",
"author": { "name": "Google LLC" },
"license": "Apache-2.0"
}
]
}
```

Users install with a Git-source `add`, optionally sparse to skip the rest of the SDK repo:

```
/plugin marketplace add GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK --sparse .claude-plugin plugins/claude_code_dist
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing
```

**Critical constraint:** the marketplace MUST be added via the Git source form (`/`), **not** by passing a direct URL to `marketplace.json`. Relative `source` paths only resolve when Claude Code has a local checkout of the surrounding repo to walk into. A direct-URL `add` fetches only the catalog JSON; the install would then fail to resolve `./plugins/claude_code_dist/...`.

Status:
- [x] **B0.1.** PR [#252](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/252) opened with the catalog + dist folder + README install-path swap.
- [ ] **B0.2.** Merge #252.
- [ ] **B0.3.** `claude plugin validate .` against the merged catalog (validates the manifest shape against the current Claude CLI schema).
- [ ] **B0.4.** Fresh-session install smoke against a scratch BQ dataset; assert `attributes.writer.version = '0.1.0'` on the resulting rows.

### B1 — Plugin distribution repo (the resolved plugin artifact, committed and tagged)

- [ ] **B1.1.** Create repo `GoogleCloudPlatform/bqaa-tracing-claude-code-plugin`.
- [ ] **B1.2.** Populate it with the **built** plugin tarball contents (not source — `vendor/` is generated and gitignored in source, and the source `plugin.json` has the `0.0.0+local` placeholder):
```
bqaa-tracing-claude-code-plugin/
├── .claude-plugin/plugin.json # stamped 0.1.0
├── hooks/
├── commands/
├── scripts/
├── vendor/ # includes .dist-info/METADATA so writer.version resolves
├── MARKETPLACE.md
└── README.md
```
Source: extract `bigquery-agent-analytics-tracing-claude-code-0.1.0.tar.gz` from the GitHub release.
- [ ] **B1.3.** Tag the repo:
```bash
git tag -a v0.1.0 -m "bqaa tracing claude code plugin 0.1.0"
git push origin v0.1.0
```
- [ ] **B1.4.** Add release automation to this repo so future `tracing-vX.Y.Z` cuts on the SDK repo automatically PR the new tarball contents over and tag here. Can be a separate follow-up — manual sync is fine for v0.1.0.

### B2 — Marketplace catalog repo

- [ ] **B2.1.** Create repo `GoogleCloudPlatform/bqaa-tracing-marketplace`.
- [ ] **B2.2.** Add `.claude-plugin/marketplace.json` with a **`github` source** pointing at the distribution repo's tag:
```json
{
"name": "bqaa-tracing",
"owner": {
"name": "Google LLC",
"url": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK"
},
"plugins": [
{
"name": "bigquery-agent-analytics-tracing",
"description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
"version": "0.1.0",
"author": { "name": "Google LLC" },
"source": {
"source": "github",
"repo": "GoogleCloudPlatform/bqaa-tracing-claude-code-plugin",
"ref": "v0.1.0"
},
"homepage": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/plugins/claude_code",
"repository": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK",
"license": "Apache-2.0",
"keywords": ["bigquery", "agent-analytics", "observability", "tracing", "claude-code"]
}
]
}
```
**Verify the exact field naming** (`source.type` vs `source.source`, `ref` vs `tag`) against the current Claude Code docs and the version of `claude` CLI you're running. Some doc versions use `\"source\": \"github\"` shorthand for simple entries.

### B3 — Validate locally before going public

- [ ] **B3.1.** From a clone of `bqaa-tracing-marketplace`:
```bash
claude plugin validate .
```
Resolve any schema errors. Iterate on the manifest shape until validation passes.
- [ ] **B3.2.** Load the local marketplace in a fresh Claude Code session:
```
/plugin marketplace add /path/to/local/bqaa-tracing-marketplace
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing
/bqaa-setup
```
Send one real prompt, then query BigQuery:
```sql
SELECT event_type, JSON_VALUE(attributes, '$.writer.version') AS writer_version,
agent, timestamp
FROM `your-project.your_dataset.agent_events`
WHERE agent = 'claude-code'
ORDER BY timestamp DESC LIMIT 5
```
Expected: `writer_version = '0.1.0'`.

### B4 — Publish + announce

- [ ] **B4.1.** Push the marketplace repo public.
- [ ] **B4.2.** Update `plugins/claude_code/README.md` in this repo to replace the curl-and-extract recipe with the marketplace install:
```
/plugin marketplace add GoogleCloudPlatform/bqaa-tracing-marketplace
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing
```
- [ ] **B4.3.** Open a PR on this repo that updates the install docs + adds a pointer to the marketplace repo from `MARKETPLACE.md`.

### B5 — Submit to Anthropic's official marketplace (after B1–B4 settle)

- [ ] **B5.1.** Once the self-hosted catalog has been validated by users for at least one release cycle, package the submission to Anthropic:
- Plugin distribution repo URL + tag
- Marketplace catalog repo URL
- `MARKETPLACE.md` verification checklist (already in this repo)
- Live BigQuery dry-run evidence ([#242 comment](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/242#issuecomment-4549835370))
- Plugin metadata from `.claude-plugin/plugin.json`
- [ ] **B5.2.** Submit via the process documented at .

## Ongoing release routine (after both tracks are live)

Once Trusted Publishing + marketplace catalog are wired up, the steady-state release process is:

1. Bump `producers/pyproject.toml` version → PR → merge.
2. `git tag -a tracing-vX.Y.Z` → `git push origin tracing-vX.Y.Z` on this repo.
3. `release-tracing.yml` does the rest (verify → build → github-release → publish-testpypi → publish-pypi).
4. Download `bigquery-agent-analytics-tracing-claude-code-X.Y.Z.tar.gz` from the new GitHub release. Extract into `bqaa-tracing-claude-code-plugin` repo, commit, tag `vX.Y.Z`, push.
5. Open PR on `bqaa-tracing-marketplace` bumping `marketplace.json`'s `version` and `source.ref`. Merge.
6. Smoke test: fresh Claude Code session → `/plugin install` → confirm BigQuery rows tag with the new version.

Step 4 can be automated as a follow-up (cross-repo workflow trigger from this repo on `tracing-v*` tags).

## References

- #229 — umbrella issue (move tracing producers to this repo)
- #234 — publish + plugin milestone
- #242 — marketplace polish (just merged)
- #249 — version bump 0.1.0.dev0 → 0.1.0 (just merged)
- [Trusted Publishing setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
- [Claude Code marketplace docs](https://code.claude.com/docs/en/plugin-marketplaces)
- [Existing release workflow](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/.github/workflows/release-tracing.yml)
- [RELEASING.md runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/producers/RELEASING.md)