Contributor onboarding: Grafana dashboard and Claude Code tracing plugin

## Goal

Give a new contributor everything needed to independently develop, test,
document, and provide completion evidence for:

1. The BQAA Grafana dashboard.
2. The BQAA Claude Code tracing plugin.

Use only synthetic data and an approved non-production GCP project. Production
data, production credentials, repository administration, and release secrets
are out of scope for the contributor.

## Current state (2026-09-04)

### Grafana

- Core implementation landed in [PR #373](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/373).
- Local one-command setup landed in [PR #422](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/422).
- Query and public-demo hardening landed in [PR #433](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/433).
- [Issue #339](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/339) remains open.
- The remaining assignment should focus on clean-environment validation,
documentation corrections, defects found during testing, evidence, and
tracker closure—not rebuilding the dashboard.

### Claude Code plugin

- The hook implementation, plugin build, and in-repository marketplace exist.
- [`plugins/claude_code/`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/plugins/claude_code)
is the plugin wrapper and documentation.
- The canonical Python implementation is under
[`producers/src/bigquery_agent_analytics_tracing/`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/producers/src/bigquery_agent_analytics_tracing).
Do not implement Python behavior in a generated plugin copy.
- The producer source version is `0.2.0`, while the checked-in marketplace
distribution is still `0.1.0`.
- PyPI and release prerequisites remain tracked by
[#349](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/349)
and the canonical operator checklist in
[#353](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/353).

## Maintainer: complete before assigning work

- [ ] Record contributor GitHub handle: `@`.
- [ ] Assign a technical owner: `@`.
- [ ] Assign a reviewer who can approve and merge PRs: `@`.
- [ ] Confirm whether the contributor uses a fork or may push feature branches.
- [ ] Confirm the [Google CLA](https://cla.developers.google.com/about) is satisfied.
- [ ] Provide an approved, billing-enabled, non-production GCP project.
- [ ] Create or identify a disposable BigQuery dataset.
- [ ] Confirm who owns Grafana Cloud access and public-sharing permission.
- [ ] Confirm whether Claude Code marketplace testing is included.
- [ ] Confirm whether the assignment stops at release readiness or includes
operating the `0.2.0` release.
- [ ] Keep Google-internal links, email addresses, credentials, and access
tickets out of this public issue.

## Shared workstation requirements

The contributor needs:

- Git and GitHub CLI.
- Python 3.12 preferred; the packages support Python 3.10–3.14.
- An isolated Python virtual environment.
- Google Cloud CLI, including `gcloud` and `bq`.
- Access to the approved GCP sandbox project.
- No production access.

Start with:

```bash
gh auth status
git clone https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK.git
cd BigQuery-Agent-Analytics-SDK

python3.12 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev]"
```

Read before contributing:

- [Repository README](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/README.md)
- [Contribution guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/CODE_OF_CONDUCT.md)
- [Security policy](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/SECURITY.md)

---

## Workstream A — Grafana dashboard

### A1. Learn the component

Read these in order:

1. [Grafana README](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/README.md)
2. [Query conventions and file-to-panel map](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/queries/README.md)
3. [Public-demo query rules](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/queries/public-demo/README.md)
4. [Interactive dashboard JSON](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/bqaa-dashboard.json)
5. [Public-demo dashboard JSON](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/bqaa-public-demo.json)
6. [Datasource provisioning example](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/grafana/datasource.example.yaml)

Important concepts:

- `queries/*.sql` is the source of truth.
- Grafana JSON embeds a copy of each SQL query.
- Change the SQL file first, then update the matching dashboard panel.
- Interactive identifiers and prices must remain `Constant` variables.
- Public-demo queries must have no Grafana variables or macros and must retain
the half-open 72-hour limit.
- Never add Trace Detail or real production identifiers to the public demo.

### A2. Obtain test resources

Required:

- An approved test GCP project.
- A disposable BigQuery dataset.
- BigQuery API and Cloud Resource Manager API enabled.
- Application Default Credentials for local testing.
- Grafana Cloud Free with dashboard-editor/public-sharing permission, or local
Grafana for initial work.
- Google BigQuery datasource plugin.

For local ADC:

```bash
gcloud auth application-default login
gcloud config set project TEST_PROJECT
```

For a Grafana service account:

- `roles/bigquery.jobUser` on the query project.
- `roles/bigquery.dataViewer` on the test dataset only.
- Do not grant Owner or Editor.
- Never commit a JSON key.
- Use a separate demo-only identity for a publicly shared dashboard.

References:

- [Grafana BigQuery datasource](https://grafana.com/grafana/plugins/grafana-bigquery-datasource/)
- [Grafana public dashboards](https://grafana.com/docs/grafana/latest/dashboards/dashboard-public/)
- [Google ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc)
- [BigQuery IAM](https://cloud.google.com/bigquery/docs/access-control)

### A3. Create safe test data

```bash
bqaa seed-events \
--scenario retail-returns \
--project-id TEST_PROJECT \
--dataset-id TEST_DATASET \
--events-table agent_events \
--sessions 100

bq-agent-sdk views create-all \
--project-id TEST_PROJECT \
--dataset-id TEST_DATASET \
--table-id agent_events
```

Verify that the table is non-empty and recent:

```bash
bq query --use_legacy_sql=false \
'SELECT COUNT(*) AS events, MAX(timestamp) AS latest
FROM `TEST_PROJECT.TEST_DATASET.agent_events`'
```

### A4. Run and inspect the dashboard locally

```bash
python3 grafana/run_local.py \
--project TEST_PROJECT \
--dataset TEST_DATASET
```

Verify:

- All dashboard rows and panels load without query errors.
- Agent, User ID, Event Type, and Session filters behave as documented.
- Clicking a recent session drives Trace Detail.
- Empty filter intersections show an honest no-data state.
- Token, latency, error, and estimated-cost panels have sensible values.
- The datasource retains the configured `MaxBytesBilled` limit.
- No service-account credential appears in Git output.

Stop the local instance afterward:

```bash
python3 grafana/run_local.py --stop
```

### A5. Make and validate changes

When changing a panel:

1. Edit its canonical `.sql` file.
2. Paste the identical query into the matching dashboard JSON panel.
3. If adding a panel, update the appropriate mapping in
`scripts/check_grafana_queries_sync.py`.
4. Update the documented file-to-panel map.
5. If it belongs in the public demo, create the separate bounded query under
`queries/public-demo/`.

Run:

```bash
python3 scripts/check_grafana_queries_sync.py
python3 -m pytest -q tests/test_grafana_local_runner.py
```

Both must pass before opening a PR.

### A6. Validate public sharing

Use only a dedicated synthetic dataset. Verify in an incognito/logged-out
browser:

- The dashboard loads without authentication.
- Every panel is inspected for query errors.
- The time picker is hidden and locked.
- Queries cannot exceed the fixed 72-hour window.
- Trace Detail is absent.
- No real user IDs, prompts, responses, credentials, project names, or
sensitive error messages appear.
- A per-query byte cap and a BigQuery project quota are configured.
- The public link can be paused or revoked.

Do not post a sensitive public dashboard URL in this issue.

### A7. Grafana completion evidence

Post:

- Commit or PR link.
- Automated test output.
- Grafana and BigQuery plugin versions.
- Confirmation that synthetic data was used.
- Confirmation that every panel passed.
- Confirmation that incognito public-share validation passed.
- Any documentation corrections.
- Cleanup and link-revocation confirmation.

Done when the maintainer reconciles this evidence with #339 and closes or
narrows that tracker.

---

## Workstream B — Claude Code tracing plugin

### B1. Learn which files are source and which are generated

Read:

1. [Plugin README](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/plugins/claude_code/README.md)
2. [Marketplace and IAM checklist](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/plugins/claude_code/MARKETPLACE.md)
3. [Plugin manifest](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/plugins/claude_code/.claude-plugin/plugin.json)
4. [`/bqaa-setup` command](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/plugins/claude_code/commands/bqaa-setup.md)
5. [Producer package README](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/producers/README.md)
6. [Plugin build script](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/producers/scripts/build_claude_plugin.py)
7. [Release runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/producers/RELEASING.md)
8. [Claude marketplace catalog](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/.claude-plugin/marketplace.json)

Rules:

- Python behavior belongs in `producers/src/bigquery_agent_analytics_tracing/`.
- `plugins/claude_code/vendor/` is generated and gitignored. Never edit it
manually.
- `plugins/claude_code_dist/` is a released artifact, not canonical source.
- `0.0.0+local` in the source manifest is intentional; the build stamps the
release version.
- Build in a disposable checkout or worktree because the build stamps the local
manifest and generates vendor files.

### B2. Install development dependencies

Required:

- Current Claude Code CLI and an approved Claude entitlement.
- Python 3.12 development environment.
- GCP sandbox project and dataset for live smoke testing.
- `google-cloud-bigquery`.
- `google-cloud-bigquery-storage` and `pyarrow` for the preferred Storage Write
path.

```bash
cd producers
python3.12 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev,receiver,storage-write]"
claude --version
```

References:

- [Claude Code plugins](https://code.claude.com/docs/en/plugins)
- [Claude Code marketplace documentation](https://code.claude.com/docs/en/plugin-marketplaces)

### B3. Run automated checks

```bash
cd producers

isort --check-only src/ tests/ scripts/
pyink --check src/ tests/ scripts/
python3 -m pytest -q
```

For focused plugin work, at minimum run:

```bash
python3 -m pytest -q \
tests/test_claude_code.py \
tests/test_setup_check.py \
tests/test_build_claude_plugin.py \
tests/test_drain.py \
tests/test_logger_row_shape.py
```

### B4. Build and validate the plugin artifact

Follow the same sequence as CI:

```bash
cd producers
python3 -m pip install --require-hashes -r build-requirements.lock
python3 -m build --no-isolation
python3 -m pip install --no-deps \
dist/bigquery_agent_analytics_tracing-*.whl
python3 scripts/build_claude_plugin.py

cd ..
claude plugin validate plugins/claude_code --strict
claude plugin validate . --strict
```

Inspect the generated tarball and confirm it contains:

- `.claude-plugin/plugin.json` with the release version.
- All nine hook scripts plus `common.sh`.
- `commands/bqaa-setup.md`.
- `scripts/run_setup_check.sh`.
- Vendored package source.
- Matching `.dist-info/METADATA`.
- No `__pycache__`, `.pyc`, credentials, or local configuration.

### B5. Test safely before connecting BigQuery

Start with dry-run mode:

```bash
export BQAA_PROJECT_ID=TEST_PROJECT
export BQAA_DATASET=TEST_DATASET
export BQAA_PYTHON="$(command -v python3)"
export BQAA_AGENT_NAME=vendor-plugin-smoke
export BQAA_DRY_RUN=true
export BQAA_TRACE_ENABLED=true

claude --plugin-dir plugins/claude_code
```

Inside Claude Code, run `/bqaa-setup`, then submit a harmless test prompt and
verify the dry-run log and spool behavior. The plugin must never break the
Claude Code session when tracing fails.

### B6. Run the BigQuery smoke test

The test identity requires:

- `roles/bigquery.dataEditor` on the destination dataset.
- `roles/bigquery.user` on the project.
- `roles/bigquery.metadataViewer` on the dataset when auto-creating the table.

Use a pre-created dataset where possible. Disable dry-run, launch a fresh Claude
Code session, run `/bqaa-setup`, and submit one harmless prompt.

Verify rows:

```sql
SELECT
event_type,
JSON_VALUE(attributes, '$.writer.version') AS writer_version,
JSON_VALUE(attributes, '$.writer.label') AS writer_label,
agent,
timestamp
FROM `TEST_PROJECT.TEST_DATASET.agent_events`
WHERE agent = 'vendor-plugin-smoke'
ORDER BY timestamp DESC
LIMIT 20;
```

Expected:

- Hook rows arrive.
- `writer_version` matches the built artifact and is not `0.0.0+local`.
- Only one BQAA plugin installation is active; duplicate installations cause
duplicate telemetry.
- Setting `BQAA_TRACE_ENABLED=false` and restarting Claude Code produces no new
rows and no agent error.

### B7. Validate the marketplace path

Before testing, run `/plugin list` and remove or disable older BQAA plugin
installations.

Validate the current Git-based install path:

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

Add the marketplace using `owner/repository`, not a direct URL to
`marketplace.json`, because its plugin source is a relative repository path.

For a `0.2.0` release, repeat this smoke only after the checked-in distribution
and catalog have been refreshed from the final built artifact.

### B8. Claude Code completion evidence

Post:

- Commit or PR link.
- Claude Code and Python versions.
- Full and focused test results.
- `claude plugin validate --strict` output.
- Tarball inventory and version.
- `/bqaa-setup` READY result.
- Redacted BigQuery query result proving the writer version.
- Kill-switch test result.
- Confirmation that duplicate plugins were removed.
- Confirmation that only synthetic or non-sensitive prompts were used.
- Remaining release blockers requiring a maintainer.

## Google-maintainer-only actions

Do not assign these actions to the contributor unless they explicitly have the
required authority:

- Repository settings, Actions environments, variables, and secrets.
- Creating or configuring `tracing-testpypi`, `tracing-pypi`, and
`release-promote`.
- PyPI/TestPyPI Trusted Publisher configuration and adding second Owners.
- Organization-owned GitHub App creation and installation.
- Repository immutable-release setting changes.
- Creating or pushing the protected `tracing-v0.2.0` tag.
- Approving release promotion and PyPI deployment.
- Artifact Registry, WIF, or public receiver-image administration when #349 is
included.
- Final Anthropic official-marketplace submission.

The authoritative operator checklist is
[#353](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/353).
The contributor may prepare artifacts, smoke evidence, and PRs, but a designated
Google maintainer must perform and record privileged steps.

## Overall definition of done

- [ ] Contributor can reproduce both components from a clean checkout.
- [ ] Automated tests and strict manifest validation pass.
- [ ] Grafana works locally with synthetic data.
- [ ] Grafana public-demo safety is verified in an incognito session.
- [ ] Claude plugin produces correctly versioned test rows.
- [ ] Claude plugin kill switch works.
- [ ] No credentials or production data are committed or exposed.
- [ ] Documentation is accurate for a first-time user.
- [ ] All contributor-executable evidence is attached.
- [ ] Maintainer-only blockers are explicitly handed to an owner.
- [ ] Parent trackers are reconciled and closed or narrowed.

Start with grafana/README.md, grafana/queries/README.md, plugins/claude_code/README.md, and producers/README.md, then run the listed Grafana sync and pytest checks. Validate both workstreams only with the approved sandbox resources, recording test output, panel and plugin checks, documentation corrections, and cleanup evidence. Done means the maintainer can reconcile the evidence with #339 and the release checklist.

Written by the indexing model from the issue text.