# Scan instructions: generate a project fingerprint (chappe fingerprint v0)

These instructions are for a coding agent. Give them to your agent and have it scan the current repository and write `fingerprint.json`. If the agent is already connected to the Chappe MCP server, upload the fingerprint after the scan (see the last section).

## Purpose

Find which third-party services (APIs, SaaS, model providers, cloud services) and SDKs this project uses, down to versions, model IDs, API versions, endpoint paths and SDK methods, and where they appear in the code.

The result is used to decide whether a third party's deprecations, sunsets, breaking changes, pricing changes and rate-limit changes affect this project.

## Rules

1. **Read only**: apart from writing `fingerprint.json`, do not modify or create any file.
2. **No secrets in the output**: do not output any key, token, password or connection string. For files that hold secrets, such as `.env`, record variable names only, never values.
3. **Record locations**: give a location (`path:line`) for every finding, at most 5 per item.
4. **Mark what is uncertain**: for items you are not sure about, set `"confidence": "uncertain"` and give the reason in `note`.
5. **External services and their SDKs only**: the test is whether the code talks to a remote service run by some company. Do not record general-purpose libraries (for example lodash, requests, pydantic).
6. **Vendor ID convention**: use the lowercase English company name, for example `openai`, `anthropic`, `google`, `stripe`, `aws`, `vercel`, `twilio`, `github`, `cloudflare`, `supabase`. Put different products of the same company in `products`, for example `s3` and `lambda` for AWS.

## What to look for

1. **Dependency manifests and lockfiles**
   - Common files: `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements*.txt`, `pyproject.toml`, `poetry.lock`, `uv.lock`, `Pipfile.lock`, `go.mod`, `Gemfile.lock`, `pom.xml`, `build.gradle`, `Cargo.lock`, `composer.lock`.
   - Record the version of each vendor SDK actually installed, taking the lockfile as authoritative. Without a lockfile, record the declared version range and mark it `uncertain`.
2. **Model IDs**: model name strings in code, config files and prompt files. A model sent through a gateway (for example OpenRouter) goes under the gateway vendor, with the ID exactly as sent (`anthropic/claude-sonnet-5`); Chappe also checks it against that model vendor's retirements.
3. **API versions**: explicitly specified API version strings, for example a version number in a request header or a date-style version passed when initializing an SDK.
4. **Endpoints**: HTTP paths called directly, or a custom base URL.
5. **SDK methods**: vendor SDK methods that are called, written without variable names, for example `chat.completions.create`, `charges.create`.
6. **Indirect references**: if any of the values above come from environment variables or config files, record the variable name, where it is read, and any default or example value you can find. Look in `.env.example`, default configs, IaC and CI config.
7. **Other explicitly declared versions**: for example a webhook API version or a callback format version; put these in that vendor's `note`.
8. **Vendor developer tools the repository configures or runs**: for example Claude Code settings, hooks or plugins, `claude -p` in CI, or the Claude Agent SDK. Record the tool in that vendor's `products` (`claude-code`), with its config files in `config_refs`. Changes to such a tool reach only projects whose fingerprint shows it.
9. **Which platform serves the models**: some vendors serve the same model IDs on several platforms with different retirement dates. For Google, say in that vendor's `note` whether the code calls Vertex AI (`vertexai=True`, `GOOGLE_GENAI_USE_VERTEXAI`, a project and location, an `aiplatform.googleapis.com` endpoint, or a gateway's Vertex provider) or the Gemini API (an API key alone, `generativelanguage.googleapis.com`), with the location, or that you cannot tell.

## Output format

Write `fingerprint.json` at the repository root with the structure below. Use empty arrays for empty fields. All values below are examples. An agent that cannot write files, or reads the repository without a checkout (for example through the GitHub API), skips the file: it builds the same JSON object in memory, passes it to `register_project` (or `check_impact`) directly, and puts the hash of the commit it read in `commit`.

```json
{
  "schema": "chappe.fingerprint/v0",
  "repo": "owner/name",
  "commit": "commit hash of the current HEAD",
  "scanned_at": "2026-10-24T08:00:00Z",
  "vendors": [
    {
      "vendor": "examplepay",
      "products": ["payments"],
      "sdks": [
        {"ecosystem": "npm", "name": "examplepay-node", "version": "14.2.0", "source": "package-lock.json", "confidence": "certain"}
      ],
      "models": [],
      "api_versions": [
        {"value": "2024-06-20", "where": ["src/pay.ts:8"], "confidence": "certain"}
      ],
      "endpoints": [],
      "methods": [
        {"value": "charges.create", "where": ["src/pay.ts:21"], "confidence": "certain"}
      ],
      "config_refs": [
        {"name": "EXAMPLEPAY_API_VERSION", "where": ["src/config.ts:5"], "default": null, "note": "the API version may also be overridden by an environment variable"}
      ],
      "note": ""
    }
  ]
}
```

`ecosystem` takes one of these values: `npm`, `pypi`, `maven`, `go`, `rubygems`, `cargo`, `nuget`, `composer`.

In `models`, `api_versions`, `endpoints` and `methods`, `value` holds only the identifier, exactly as the code uses it: a model ID (`gpt-6-luna`, or `openai/gpt-6-luna` when the code sends that), an API version string, an endpoint as the HTTP method the code uses plus the path (`POST /v1/chat/completions`; leave the method out only when the code does not show it, since a change to writes must not match a project that only reads), or a method name (`chat.completions.create`). Put anything else, such as the parameters used, the provider it goes through or why it matters, in that item's `note`.

## Upload the fingerprint (when connected to Chappe MCP)

1. Call Chappe's `register_project` tool: `name` is the repository name, `repo` is `owner/name`, `fingerprint` is the JSON object generated above.
2. Tell the user the returned `project_id`, and list each item in `impact.affected` as "title, deadline, code locations". For `impact.unknown`, say how many there are and list at most 10 of them, those with the nearest deadline first, by title and reason; offer to list the rest.
3. Do not change any code on your own; wait for the user to decide.

## When done

Summarize in at most 5 lines in the conversation: how many vendors were found, which items are `uncertain`, and anything you could not find; if you uploaded, include the `project_id` and the number of affected items.
