First-run questions

I ran generate and got only one tool. Where are my other reads?

By design. Tibyaan exposes only capabilities it can prove, structurally, from your source, and today that means read-by-id and the unfiltered list. Everything else is refused on purpose, not missed:

• Writes (create, update, delete) are refused at the discovery level. They are never considered for the manifest.
• Filtered reads (findByStatus, search, and the like) are refused, because a parameter's meaning is a claim Tibyaan cannot verify from structure alone. You can carry one through attestation.
• Custom paged result-set wrappers are not seen through by discovery.

To see every decision the tool made, with its located reason, run the survey:

java -jar tibyan-cli-0.3.0-jar-with-dependencies.jar scan /path/to/your-app --report survey.md

Why does scan show more than generate, or the build plugin?

They serve two different jobs. scan is the survey: it prints the whole picture, for you, to decide whether to adopt. generate and the Maven plugin produce the artifact: they emit only the proven capabilities, because the manifest is what an agent will act on. A refusal is a deliberate absence from the artifact. See Reading your survey.

The output folder has .java files. What do I do with them?

For the Spring adoption path, nothing. You do not compile them, copy them, or wire them in. The MCP backend produces the manifest and one generated tool class per capability: two materializations of the same contract for two hosting paths. Your running app plus the runtime dependency reads the manifest. The tool classes are for a separate, hand-hosted generated project, which adopting into an existing Spring app does not use.

The manifest module field names one module. Is that a bug?

No. The module field is just the name of the directory you scanned. If you pointed the tool at one module, you get that module's capabilities only, because discovery resolves against exactly the source you scan. To cover a whole application, scan the reactor root: see Multi-module applications.

A tool vanished from my manifest after upgrading to 0.3.0. Why?

0.3.0 added a by-primary-key proof to the path that discovers entity-returning reads, which previously matched on method signature alone. On a real application that path had bound a read-by-id tool to a method that filters by a foreign key and returns the first hit: a wrong binding, which now correctly refuses. If a tool disappeared, the previous binding was not safe to rely on. Re-read the survey's refusal ledger.

Do I need the CLI if I use the Maven plugin?

No. The build plugin runs the same pipeline during your build and writes the manifest onto the classpath. The CLI is for previewing and inspecting read-only, before and independent of any build change. Use the CLI to decide, use the plugin to adopt. They generate identical output for the same source.

It felt hard to get started. What is the intended path?

1. Preview. Scan your app with --report. Read-only, changes nothing.
2. Read the survey. Refusals are expected; the one number that must stay 0 is mis-bound.
3. Adopt, only if the preview convinced you: the runtime dependency and the build plugin, then mvn package.
4. Connect an agent to http://localhost:8080/sse.

The quickstart walks through all four with copy-paste commands.