# xpsflow: instructions for agents

xpsflow analyzes X-ray photoelectron spectroscopy (XPS) data under physical constraints and
reports every number with its provenance. This file says when to reach for it and how.

## When to use this

- The user has an XPS file (Kratos `.kal`, ISO 14976 VAMAS `.vms`, or a two-column text export)
  and wants it graded, calibrated, identified, fitted, quantified or reported.
- The user asks a reference question: the binding energy of a chemical state, which element a
  peak near some energy belongs to, a doublet's splitting and ratio, or what constraints a fit of
  a given region should carry. Answer from the curated tables and quote the citation they carry.
- The user wants several samples compared on the same footing (`xpsflow batch`).

## When not to use this

- Hyperspectral maps, depth-profile chemometrics, or files that cannot be exported to VAMAS.
- Any request to produce a composition or a binding energy without data or without a table
  entry. The tools never invent a number; neither should you.

## How to call it

1. Reference questions, no install: POST JSON-RPC to the hosted MCP endpoint `https://xpsflow.pages.dev/mcp`
   (streamable HTTP, no authentication). Tools: `lookup_element`, `lines_near`,
   `find_chemical_state`, `list_templates`, `get_template`, `read_docs`. The same data is plain
   JSON under `https://xpsflow.pages.dev/reference/` (start at `index.json`).
2. Analysis, with the local install (`pip install "xpsflow[mcp]"`): start `xpsflow mcp --data DIR`
   and follow the order `load_data` -> `check_quality` -> `calibrate_energy` -> `identify_survey`
   -> (`use_template` | `propose_fit`) -> `fit_spectrum` per narrow scan -> `quantify`. Read the
   `audit` block of every fit before quoting its numbers. Spectrum keys are `<file stem>/<label>`;
   use them verbatim.
3. Over HTTP: `xpsflow serve`, then the API at `http://127.0.0.1:8765` described by
   `https://xpsflow.pages.dev/openapi.json`. `GET /api/tools` lists the tools; `POST /api/tool/{name}` calls one.
   Errors are JSON with `error.code`, `error.message` and `error.hint`.
4. In a shell: `xpsflow run FILE --out DIR` writes `results.json`, the templates used and a report.

## What to tell the user

- Quote the composition with its intensity scale (which transmission function, which sensitivity
  factors) and say which of the three readings you are quoting (as measured, carbon excluded,
  overlayer corrected).
- Pass on the audit findings and the quality grades; a `poor` survey means its rough composition
  is a sketch.
- The last page of every report is a sign-off for a human. Say so.

## Where things are

- Overview and index: `https://xpsflow.pages.dev/llms.txt`; every page in one file: `https://xpsflow.pages.dev/llms-full.txt`
- Every documentation page has a Markdown twin at its address with `.md` appended, or on
  `Accept: text/markdown`.
- MCP server card (hosted and local transports): `https://xpsflow.pages.dev/.well-known/mcp/server-card.json`
- Source and issues: https://github.com/KarthikSubramanian07/XPS-Flow