# Docs

The **Docs** tab is your live reference for whatever transformation file you're working on. Select a file in the navigator on the left, and the Docs tab shows you exactly what that file receives on `params`, what it can return, which [Secrets](/playground/transformation/secrets.md) are currently available to it (scoped to edge or browser), and a complete example tailored to that file.

It's dynamic: add a Secret in the Secrets tab, and the Docs tab immediately lists it by name under the right scope and updates the Example to reference it. You never have to leave the UI to look up a param shape, a return field, or a Secret name.

### What each file's reference contains

Every  file (`tagRoot`, `tagChannel`, `tagInstance`, `clientTagRoot`, `clientTagChannel`, `clientTagInstance`) has the same sections in the Docs tab:

* **When it runs** — where in the event pipeline this file fires: edge vs. browser, once per event vs. per provider vs. per provider instance.
* **Input (params)** — the full TypeScript shape of the `params` object this file receives (`payload`, `user`, `variables`, `platform`, `userCustomData`, `hostData`, `logger`, `userKey`, `providerData`; plus `providerId` for channel and instance levels, plus `settings` for browser files).
* **Return shape** — the fields you can return (`payload`, `user`, `additionalEvents`, `skipEvent`) and what each does for this specific level. Levels where `additionalEvents` isn't honored (anything that isn't a root file) say so explicitly.
* **Helpers** — for edge files, usage blocks for `params.userKey.getFirstClick()` / `getLastClick()` and `params.providerData`, including the literal-provider-ID return set and the click-ID-by-provider shape. For all files, `params.logger`.
* **Secrets** — the list of Secrets currently available to this file. Edge files show every Secret; browser files show only those with the client flag. Each is listed as `params.variables.NAME`. When nothing is configured, you see a placeholder pointing at the Secrets tab.
* **Example** — a complete, copy-pasteable example tailored to this file. The example uses `providerId` in channel/instance files, `settings` in browser files, and references your configured Secrets where relevant.

### Dynamic sections

The **Secrets** section reflects your current configuration in real time:

* Add a Secret named `API_KEY` → edge files now list `params.variables.API_KEY` under Secrets, and the Example updates to reference it.
* Mark that Secret as client-side → it also appears in the Secrets section for `clientTagRoot`, `clientTagChannel`, and `clientTagInstance`.
* Unmark the client flag → it disappears from the browser files' Docs but stays on the edge files.

The name you see in Docs is the name you use in code.

### Switching between files

The file navigator on the left lists every file. Clicking one updates the Docs tab to the reference for that file. Because the six levels share most of their `params` shape, a common workflow is:

1. Read the Docs for `tagRoot` to understand the base shape and helpers.
2. Switch to `tagChannel` to see what `providerId` adds.
3. Switch to `clientTagRoot` to see how browser params (`settings`, scoped `variables`) differ.

{% hint style="info" %}
Use Docs alongside the [Code](/playground/transformation/code.md) tab while you're writing — Code shows your code, Docs shows the contract. They're designed to be read side by side.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgetag.io/playground/transformation/docs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.