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.

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 and select your agent.
2. In the Overview tab, find the Faustine in this app card.

The card shows one line for each difference.

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.

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.

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.

- 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.

npx skills add faustine-ai/skills

Then, in your coding agent:

/sync-faustine-adapter

Troubleshooting

Next steps

• faustine-next CLI: every flag and exit code.
• The Faustine adapter for Next.js: the registry, the handler and the three states.
• Keep the agent up to date: how a push reaches the analysis.
• Agent skills: the skills that install and sync the adapter.