> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install with Claude Code

> Copy one prompt into Claude Code, Cursor or Codex and let your coding agent add Puntego to your app, wire the CSP, and check that the launcher appears.

Your coding agent can do the whole install for you. Paste the prompt below into Claude Code, Cursor, Codex or any agent that can edit your repository and run your app. It finds your framework, adds Puntego once in the root layout, updates your Content Security Policy if you have one, then runs the app and checks that the launcher appears.

<Steps>
  <Step title="Copy your app ID">
    Open **Dashboard → Install** and copy the **test snippet**'s app ID (it starts with `gp_test_`). The test key boots on any page, `http://localhost:3000` included, with no domain to verify, so the agent can see the guide on your dev server. Swap in your production `gp_` app ID when you ship on a [verified domain](/domains).
  </Step>

  <Step title="Paste the prompt into your agent">
    Replace `gp_your_app_id` on the first line with the ID you copied, then paste the whole prompt. The app ID is public, so it is safe in client code; the install needs no API key.
  </Step>

  <Step title="Review the diff">
    The agent should change one root layout or entry file, and your CSP if you have one. Read the change before you commit it.
  </Step>
</Steps>

## The prompt

```text theme={null}
Install Puntego (an in-product guide that answers, points at elements and runs tours) in this app.
My Puntego app ID is: gp_your_app_id
Docs: https://docs.puntego.com/install and https://docs.puntego.com/frameworks

Follow these rules exactly. Do not invent options, attributes or packages that are not listed here.

1. Detect the framework from package.json and the project structure (Next.js App Router,
   React with Vite/CRA/Remix, Vue, Svelte/SvelteKit, Angular, or a plain HTML site).
   Find the single root layout or app shell that renders on every page.

2. Choose ONE boot strategy for the whole page. Never add both a package and the script tag.
   The @puntego/* packages publish to npm at launch. Run `npm view @puntego/react version`.
   - If it prints a version, use the package for the framework:
     - Next.js or React: install `@puntego/react @puntego/embed react` with the project's
       package manager, then wrap the app once, in the root layout, in
       <PuntegoProvider appId="APP_ID">{children}</PuntegoProvider>
       imported from '@puntego/react'. It is safe to render from a Next.js server layout.
       `apiUrl` is optional (it defaults to the public Puntego worker).
     - Vue, Svelte, Angular or anything else: install `@puntego/embed` and call
       loadPuntego({ appId: 'APP_ID' }) from '@puntego/embed/loader' exactly once on the
       client, in the root component's mount hook (Vue onMounted, Svelte onMount, an Angular
       root service guarded by isPlatformBrowser).
   - If it fails (npm 404), use the script tag instead, rendered once on every page near the
     end of <head> or just before </body> of the root HTML template or layout. Convert the
     attribute names to the framework's syntax (for example crossOrigin in JSX):
       <script
         async
         src="https://puntego.com/boot.js"
         data-app-id="APP_ID"
         data-gp-api="https://worker.puntego.com"
         crossorigin="anonymous"
       ></script>
     Keep data-gp-api: without it the guide never mounts.

3. If the app sets a Content-Security-Policy (search headers config, middleware, meta tags and
   the server), merge these entries into it. Do not replace the existing policy:
   - script-src: https://puntego.com and the page nonce ('nonce-...')
   - connect-src: https://worker.puntego.com
   - style-src: the page nonce
   - img-src: data:
   - if the policy uses Trusted Types, add puntego-loader, puntego-boot and puntego
     to the trusted-types directive
   - if the policy also sets script-src-elem or style-src-elem, add the same entries
     there too: those directives win over script-src and style-src for elements
   Pass the same per-request nonce to Puntego: the `nonce` prop on PuntegoProvider, the
   `nonce` option of loadPuntego, or both `nonce` and `data-nonce` on the script tag.
   If there is no CSP, change nothing.

4. Beyond what steps 2 and 3 require, add no data-* attributes, API keys or identity tokens.
   Never put a Puntego API key in client code or in a browser-prefixed environment variable.

5. Verify. Start the dev server, open the app in a browser and confirm:
   - a Puntego launcher appears in the bottom-right corner. With a gp_test_ app ID it carries
     a "Test mode" label;
   - the request to https://worker.puntego.com/boot succeeds;
   - the console shows no message starting with [puntego] E_. If one does, look the code up
     at https://docs.puntego.com/console-codes and fix what it names;
   - if step 2 used a package, `npx @puntego/cli doctor` reports no FAIL (a gp_test_ app ID
     is a WARN until you ship).
   A production gp_ app ID only boots on HTTPS pages of a verified domain, so on localhost it
   answers 403 boot/origin_not_allowed by design: use the gp_test_ app ID for local checks.

6. Report which files you changed, which boot strategy you chose and why, and the result of
   each check in step 5.
```

<Note>
  Single-page apps need nothing extra: the guide notices client-side route changes on its own. To scope the guide to some routes, change the launcher, or turn on proactive behavior, see the [script attributes](/install#script-attributes) after the install works.
</Note>

## Prefer a printed plan

Once the `@puntego/*` packages are on npm (`npm view @puntego/cli version` prints a version), the CLI prints the same install for your project without changing a file or making a network request:

```bash theme={null}
npx @puntego/cli install --app-id gp_your_app_id
```

It names the framework, the root file, the package command for your package manager, the snippet, the CSP entries to merge and the checks to run. Add `--script` for the script tag, or `--json` to hand the plan to your agent. After the change, `npx @puntego/cli doctor` checks the install. See [Validate an integration locally](/frameworks#doctor).

## Use it as a skill

If you install Puntego in more than one app, save the same instructions as a Claude Code skill so you can run it by name. Create `.claude/skills/puntego-install/SKILL.md` in your project (or in `~/.claude/skills/` to use it everywhere) with this content:

```markdown theme={null}
---
name: puntego-install
description: Install the Puntego in-product guide in this app (package or script tag), wire the CSP, and verify the launcher appears. Use when asked to add, install or set up Puntego.
---

Install Puntego in this app. Ask me for the app ID if I have not given one: it starts with
gp_test_ (test key, boots on localhost) or gp_ (production, verified HTTPS domains only).
Then follow, without inventing options, attributes or packages:

1. Detect the framework and the single root layout that renders on every page.
2. Use ONE boot strategy. If `npm view @puntego/react version` prints a version:
   Next.js/React -> install @puntego/react @puntego/embed react and wrap the app once in
   <PuntegoProvider appId="APP_ID"> from '@puntego/react'; other frameworks -> install
   @puntego/embed and call loadPuntego({ appId: 'APP_ID' }) from '@puntego/embed/loader'
   once on the client. Otherwise add this tag once, near the end of <head> or before </body>:
   <script async src="https://puntego.com/boot.js" data-app-id="APP_ID"
     data-gp-api="https://worker.puntego.com" crossorigin="anonymous"></script>
3. If a Content-Security-Policy exists, merge: script-src https://puntego.com + the nonce;
   connect-src https://worker.puntego.com; style-src the nonce; img-src data:; Trusted Types
   (if used): puntego-loader puntego-boot puntego. Mirror the script-src and style-src entries
   into script-src-elem and style-src-elem when the policy sets them. Pass the nonce via the provider's or
   loader's `nonce`, or `nonce` and `data-nonce` on the tag.
4. Beyond steps 2 and 3, no data-* attributes; no API keys or identity tokens in client code.
5. Run the dev server and confirm the launcher appears (a "Test mode" label with gp_test_),
   /boot on https://worker.puntego.com succeeds, and the console has no [puntego] E_ codes
   (see https://docs.puntego.com/console-codes). With a package, `npx @puntego/cli doctor`
   reports no FAIL (gp_test_ is a WARN until you ship).
6. Report the files changed, the strategy chosen and each check's result.
```

Then ask Claude Code to "install Puntego" in that project.

## After the agent finishes

<CardGroup cols={2}>
  <Card title="Verify your domain" icon="globe" href="/domains">
    Go live: the production `gp_` app ID only boots on verified HTTPS domains.
  </Card>

  <Card title="Full install reference" icon="settings" href="/install">
    Every script attribute, route rule, and the install diagnostics.
  </Card>

  <Card title="Framework guides" icon="layout-template" href="/frameworks">
    Declared targets, signed-in identity, and SPA details per framework.
  </Card>

  <Card title="Strict CSP" icon="shield-check" href="/csp">
    The full policy, including Verified Actions and voice.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.