# Keep the adapter in sync

Run `npx faustine-next sync` after you add, rename or remove a Server Action or a server-only data function. It updates `faustine/registry.ts` to match what the analysis found and reports the new registry to Faustine. For what the registry is, see [The Faustine adapter for Next.js](https://docs.faustine.ai/web-agents/nextjs-adapter/).

## Before you begin

- The adapter is installed: the repository has `faustine/registry.ts` or `src/faustine/registry.ts`.
- The machine has an adapter token for this agent. If `sync` answers that there is no adapter token, create a new install command on the agent's **Overview** and run `npx faustine-next init --setup <SETUP_CODE>` once.
- The code change is pushed, or uploaded as a new ZIP, so that the analysis has seen the new function.

## See what is out of step

To find what the registry is missing:

1. In the portal, go to [**Web Agents**](https://auth.faustine.ai/go?to=%2Fweb-assistants) and select your agent.
2. In the **Overview** tab, find the **Faustine in this app** card.

The card shows one line for each difference.

| The card says | Meaning | What to do |
| --- | --- | --- |
| **2 operations not bound**, with their names | The analysis found operations that the registry does not bind. Once a version is served, only the operations enabled in the portal count. | Run `sync` and deploy, or turn those actions off in the **Actions** tab. |
| **No registry in the last commit** | The last push does not contain the registry file. | Commit the registry, or run `sync` again and commit the result. |
| **Adapter updated in the repo, waiting for a deploy** | The repository has a newer registry than the running app. | Deploy your app. |
| **Broken binding** | The registry imports a function that the last commit does not have. | Run `sync`. A broken import also fails your app's build. |

A line goes away on the push or the deploy that resolves it. The same differences appear in **Settings**, under **Faustine adapter**.

## Update the registry

To bring the registry in step:

1. In the directory of the Next.js app, print what would change.

   ```terminal
   npx faustine-next sync --dry-run
   ```

   The output lists the operations it would bind and the ones it leaves out, with the reason for each.

2. Write the change.

   ```terminal
   npx faustine-next sync
   ```

   `sync` keeps every line the registry has, adds the operations that are new since the last run, and leaves out a line you removed earlier. To bind an explicit list, pass `--operations deals.createDeal,deals.getDeal`.

3. Review the diff of the registry and remove the line of any function that should stay private.
4. Commit the registry with the code change, push, and deploy your app.
5. To let the agent call a new operation, publish a version of the agent that includes its action. See [Publish a version](https://docs.faustine.ai/web-agents/publish-a-version/).

After the push the card shows **In the repo**. It shows **Deployed** once the running app has asked Faustine which operations are enabled.

## Compare the running app with Faustine

`doctor` reads the registry in the checkout, asks the running app what it serves, asks Faustine what it expects, and prints the differences.

```bash
npx faustine-next doctor --url https://app.nimbuscrm.example
```

Without `--url` it checks `http://localhost:3000`. It exits with `4` when it finds an error, such as an app that does not answer `/api/faustine/manifest`.

## Check the registry in CI

`sync --check` writes nothing and exits with `1` when `sync` would change the registry, the route handler or the `AGENTS.md` block. A pull request that adds a Server Action without binding it then fails.

The CI runner needs an adapter token. A setup code is exchanged for a token once, on one machine, so CI uses the token file of a machine that ran `init`: store it as a CI secret, and write it where the CLI reads it. The file is `~/.config/faustine/adapters/<AGENT_ID>.json`. `FAUSTINE_CONFIG_DIR` changes the directory.

```yaml filename=".github/workflows/ci.yml"
- name: Check the Faustine adapter
  env:
    FAUSTINE_CONFIG_DIR: ${{ runner.temp }}/faustine
    FAUSTINE_ADAPTER_TOKEN_FILE: ${{ secrets.FAUSTINE_ADAPTER_TOKEN_FILE }}
  run: |
    mkdir -p "$FAUSTINE_CONFIG_DIR/adapters"
    printf '%s' "$FAUSTINE_ADAPTER_TOKEN_FILE" > "$FAUSTINE_CONFIG_DIR/adapters/<AGENT_ID>.json"
    npx faustine-next sync --check
```

The token can read the agent's data surface and report its registry. Revoke it in **Settings**, under **Faustine adapter**, if the secret leaks.

## Sync with a coding agent

The `sync-faustine-adapter` skill runs the same commands, shows you the new operations one at a time and asks before it exposes one that writes or deletes.

```bash
npx skills add faustine-ai/skills
```

Then, in your coding agent:

```text
/sync-faustine-adapter
```

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `The registry binds Web Agent … but this machine has no adapter token for it` | The machine never exchanged a setup code, or its token file is missing. The command exits with `2`. | Run `npx faustine-next init --setup <SETUP_CODE>` with a new code, or restore the token file. |
| `This adapter token was revoked in the portal.` | Someone selected **Revoke** for this machine's token. | Create a new install command and run `init --setup` again. |
| `Not a terminal: pass --yes to write the files (or --dry-run to only print the plan).` | `sync` ran without a terminal, as in a script. | Add `--yes`. |
| `sync` does not add a new Server Action | The analysis has not seen it. | Push the change and wait for the update to finish, then run `sync` again. |
| `sync` does not add back a line you removed | A removed line is kept out on purpose. | Pass the operation in `--operations`, together with the ones to keep. |

## Next steps

- [faustine-next CLI](https://docs.faustine.ai/reference/faustine-next-cli/): every flag and exit code.
- [The Faustine adapter for Next.js](https://docs.faustine.ai/web-agents/nextjs-adapter/): the registry, the handler and the three states.
- [Keep the agent up to date](https://docs.faustine.ai/web-agents/keep-up-to-date/): how a push reaches the analysis.
- [Agent skills](https://docs.faustine.ai/packages/agent-skills/): the skills that install and sync the adapter.