Made of little things.

# Shell AI and native CVM reports

This branch implements two explicit choices in **AI options**:

1. **Your shell connection**: the shell owns the provider connection and API key.
   The app reviews the exact case, prompt and selected images, then requests a
   structured report through the optional experimental NAP-LLM interface.
2. **Paid report service**: an encrypted ContextVM service owns its provider,
   credentials and report logic. The app reviews its price and data handling,
   saves a recovery receipt and stages input. Native CEP-8 handles payment for
   the report tool. The shell displays the invoice, wallet controls and QR.

The local VALUE amendment is deferred. There is no VALUE API call or advertised
VALUE domain in this app. NAP-LLM remains an [upstream draft](https://github.com/napplet/naps/pull/134); paid calls use the existing
SDK NAP-CVM interface. Neither path grants ambient network access to the app.
Body mapping and drafts work without optional inference/payment features. Paid
orders require CVM and host storage for the recovery receipt.

## BYOK setup

Use a NAP-LLM-capable build of napplet.soy or soyLI. Configure a provider
in the shell's AI connections. JSON-mode support is optional: the app requests
provider-enforced JSON when advertised and otherwise requests text, applying the
same strict JSON/report validation either way. Enable image support only for a
model that accepts it. In this app, choose a model, review the input and send. Text-only
sending is an explicit choice; images are never silently discarded. Responses follow NAP-LLM PR #134 at `5e93bdfce0e84c0de728234cb7b3feed498f8635`.
The app joins final text content blocks and ignores display-only thinking. It does
not request or execute tools; unexpected blocks are rejected. Responses are buffered. Truncated, refused or invalid reports never replace a completed
report. Provider keys never enter the app. Legacy remembered keys are not read;
AI options can delete them. The old generic bridge remains historical reference.

## Report choice and privacy

In AI options, **Paid report service → Review report & price** loads the service's
price and data handling without staging medical input or creating an invoice.
The dialog shows loading and actionable errors. Only the subsequent reviewed
send action prepares an order and enters checkout. Choosing a shell model also
provides **Review report request** in the same dialog.

BYOK requests may be associated with the user's AI-provider account. The paid
route uses the service's account instead, but is not anonymous: the service and
its inference provider receive the reviewed clinical input, and the current
service associates each report with its invoice for settlement and recovery.
Encrypted transport and encrypted server storage do not hide data from the
service that processes it. Wallet, network and retention policies still apply.
See [privacy boundaries and remaining work](REPORT-PRIVACY.md).

## Service and contract

The default **AI Doc report service** uses public key
`02f43ef61bd1be1a1887b6f638db169ce5461f72a18dcf11afece1588539f8e5`
and `wss://relay.contextvm.org`. Its current model, price and retention are read
before reviewing a request. The introductory price is 42 sats; the frozen order
quote is authoritative and a change after review is rejected. **Change service
(advanced)** and the public `VITE_PAID_CVM_PUBKEY` / `VITE_PAID_CVM_RELAYS` build
settings remain available. Credentials are never build settings.

The version-2 MCP tool contract is:

| Tool | Purpose | NAP-CVM payment policy |
|---|---|---|
| `body_journal_paid_info` | Model, price, retention, payment mode | `deny` |
| `body_journal_paid_image` | Stage/hash-check selected images | `deny` |
| `body_journal_paid_prepare` | Save reviewed input/price; no invoice or inference | `deny` |
| `body_journal_paid_run` | Native CEP-8 gate, then start/recover the report | `prompt` |
| `body_journal_paid_status` | Read saved report state | `deny` |
| `body_journal_paid_confirm` | One explicit settlement check | `deny` |
| `body_journal_identity_challenge` | Issue a scoped one-use report identity challenge | `deny` |
| `body_journal_identity_execute` | Prove ownership and list/read/attach/delete reports | `deny` |

All requests require encrypted transport. Image chunks are scoped to the stable
free-call transport identity. Prepared orders use a private random 256-bit bearer
receipt, allowing paid invocations and recovery on a new transport identity.
The paid call allows up to five minutes including shell approval. A pending or
failed result never automatically repeats checkout. Stopping during checkout
closes the CVM session; it does not undo a payment or erase the saved receipt.

The private service advertises the paid tool through CEP-8. Native invoices stay
in shell checkout, not application tool results. The website reuses its Cashu
wallet and spending journal, with fee approval. soyLI provides an external-wallet
QR and copyable invoice, without borrowing publishing keys. QR fallback is also
retained for old application-invoice receipts. The proprietary service source
and credentials stay in the operator's separate private repository.

## Quiet confirmation and recovery

The Minibits receiving connection does not advertise incoming-payment events.
For it, after shell checkout use **I’ve paid — check payment** in the app. That
user action performs one receiving-wallet lookup and validates the payment. It
never sends another payment, creates another invoice or schedules a retry. The
check button remains available after the QR is removed. A verified payment lets
the paid invocation continue; payment alone does not start a native report.

Compatible receivers can use passive incoming-payment notifications. Native
CEP-8 verification waits for a recorded confirmation or push event. It does not
use the SDK NWC processor's polling fallback. Status, reload, receipt recovery,
background work and service startup/restart send no NWC commands in manual mode.

Keep the recovery receipt private: possession grants access to the report. It
travels with the original service identity even if connection settings change.
**Resume paid report** reads saved state without payment. An explicit continuation
of an already-paid order is not charged again. A stopped input upload can be
discarded before any invoice is requested. Old invoices remain recoverable.

Orders use encrypted durable storage. Invoice creation is recorded before
contacting the wallet, and inference is claimed once. Unknown invoice outcomes
or interrupted/failed inference require operator recovery; no replacement charge
or billed retry happens automatically. Completed orders drop inference input/images but retain the
report. Attached identities retain reviewed case text for report recovery and
validation. Users can delete completed reports and their recovery records; payment
journals and old encrypted pages may remain in backups. Recovery/refunds, deletion and
off-host backups need separate operator acceptance. Payment is not a guarantee
of successful report delivery.

## Verification and rollout

The compatible shell implementation was merged and deployed on 6 November 2026 through [NAP-LLM PR #45](https://github.com/soytec/napplet-soy/pull/45) and [native CVM checkout PR #49](https://github.com/soytec/napplet-soy/pull/49).
On napplet.soy, sign in and configure a shell AI connection before selecting a BYOK model. Other hosts need both interfaces to offer both report paths. The app joins NAP-LLM final text blocks
and keeps display-only thinking out of report JSON. Native checkout remains
separate from NAP-LLM and does not introduce a VALUE extension.

- `pnpm verify`: application, guidance, validation, types and build.
- `pnpm test:ai:ui`: synthetic BYOK, native-call policy, pending/paid recovery,
  one explicit confirmation, invalid-report retention and responsive layouts.
- `pnpm test:conformance`: five passed, five skipped; manifest, wire and teardown
  evidence is not supplied. No universal interoperability claim follows.
- The shell's tests cover real encrypted SDK gating and real browser checkout,
  wallet approval, QR removal, duplicate-payment protection and cancellation.
- Private service tests cover native gating, one invoice/report, restart recovery
  and zero background NWC requests. All payments/providers are synthetic.

Funded settlement, live image-report acceptance, independent-shell checkout and
clinical accuracy remain unverified. The user deferred funded payment testing.
A prior real-service synthetic order produced one unpaid invoice and recovered
it after reload; that predates this native payment migration.

The current soyLI preview scopes storage to the artifact hash. Export your private
receipt before rebuilding; if storage appears empty, restore it through **AI
options → Restore a paid report receipt**. Ordinary reload retains saved state.

## Release acceptance — 2026-11-06

The app includes both shell-owned BYOK and the paid CVM report flow, with the
invoice QR fallback and explicit manual confirmation. The native private service
is deployed: encrypted discovery, synthetic preparation, duplicate preparation
and state recovery passed without creating an invoice or running inference.
A continuous 90-second passive observation spanning service restart/readiness
and recovery saw zero receiving-wallet requests.

Application verification, content-block BYOK/paid-recovery browser scenarios,
responsive checks and shared-host sandbox startup passed. Upstream conformance
reports five passes and five skips. Full funded settlement, real provider/image
report acceptance and independent-shell checkout remain unverified; funded
payment testing was explicitly deferred. Production playback and the live service price/provider review were verified.
A standalone soyLI binary release is separate from the hosted shell deployment.

Managed creator skills use napplet/web
`e2f075e74f8c03ef38b3b32b7147838cd82eda7a`, with the original scaffold pin retained.
The update preserved app code and produced no managed-file conflicts. The
public source contains the application and reference guidance; proprietary
paid-service implementation and credentials stay in a separate private repo.

## Reusable report identity — 7 November 2026

The service advertises `reportIdentity: true` as an additive version-2 capability.
The napplet offers local key creation/import, a printable QR/PDF recovery key,
optional remembering and multi-report history. Proofs use ordinary encrypted MCP
tool arguments; NAP-CVM transport and CEP-8 payments are unchanged. See
[identity and privacy](REPORT-PRIVACY.md) for the ownership, recovery and deletion
contract and the limits of ordinary Lightning payments. No private report identity
is sent to the receiving wallet.