# Set up Updog in a repository

Use this guide when a user asks you to “set up Updog in this repo.” The canonical documentation is https://wuzupdog.com/docs and the canonical source organization is https://github.com/wuzupdog.

## 1. Detect the stack

Inspect the repository before editing it:

- `mix.exs` or Phoenix modules: use `wuzupdog/updog_elixir_client`.
- `Gemfile` or `*.gemspec`: use `wuzupdog/updog_ruby_client`.
- `Packages/manifest.json` and Unity assets: use `wuzupdog/updog_unity_client`.
- `src-tauri/Cargo.toml` or a Rust desktop process: use `wuzupdog/updog_tauri_client`.
- A human or agent that needs to investigate Updog telemetry: use `wuzupdog/updog_cli`.

Read the selected repository's current README and package metadata before changing the target repository. Do not install a similarly named package from another owner.

## 2. Install the maintained client

The SDKs currently install from their canonical GitHub repositories while native package-registry releases are prepared. See https://wuzupdog.com/docs/clients.json for structured install metadata.

Prefer a released version or immutable Git reference when the selected client provides one. Do not silently pin an arbitrary commit; tell the user when only a source install is available.

## 3. Configure resource identity

Read the ingestion secret from `UPDOG_API_KEY`. Also configure these fields when the runtime knows them:

- `service`: stable application or process name.
- `environment`: for example `production`, `staging`, or `development`.
- `release`: deploy version or Git SHA.
- `hostname`: let the client derive it unless the runtime needs an explicit value.

Use the default endpoint `https://wuzupdog.com` unless the user says the project is self-hosted.

Never place an API key in source code, a checked-in environment file, test output, a command-line argument, or an agent response. Wire only the environment-variable reference. If the user has not created a key, instruct a project owner or admin to create an **ingestion** key on the Updog project page and store it in the deployment secret manager.

## 4. Integrate at the right lifecycle points

- Keep capture calls non-blocking. Use the client's standard initialization and framework integration.
- Preserve the client defaults for bounded queues, batching, retries, and shutdown unless the repository has a documented reason to tune them.
- Add a bounded flush to short-lived jobs or graceful shutdown where the selected client requires it.
- Do not initialize the Unity client in player/client builds or ship an ingestion key to end-user devices.

## 5. Verify the setup

Run the target repository's formatter, compiler, and tests. Exercise one intentional error in a development or test environment, flush the client, and ask the user to confirm that the event arrived in the intended Updog project. Do not send a synthetic production error unless the user explicitly requests it.

## Optional: give the repository read-only production context

Install the Updog CLI from https://github.com/wuzupdog/updog_cli/releases/latest and run `updog login`. A project owner or admin approves one project in the browser. The CLI stores the credential in the operating-system credential manager.

Add guidance—not credentials—to the repository's `AGENTS.md`:

```md
Use `updog --project <profile> --json logs search` and
`updog --project <profile> --json errors search` when diagnosing production.
Updog access is project-scoped and read-only. Run these commands on the host.
```

Use an explicit `--project` profile in agent commands so the target never depends on ambient default state.