docs: AI agent operations, prompts/models, testing guide, and contract error reference

[0xDeon]

Adds four reference documents. Everything here was written against the source and checked against it, rather than from the issue descriptions alone.

Retargeted onto dev — my first attempt (#601) went to main and was auto-closed by the branch-policy bot. Same commit, rebased onto dev.

Closes #586
Closes #585
Closes #584
Closes #580

---

apps/ai_agent/docs/operations.md — #586

Production uvicorn invocation and worker sizing, and why the python main.py path in the __main__ guard is development-only.

/health is documented as a liveness probe, not a readiness probe. It returns 200 with no API key set and with Weaviate down, because the handler performs no dependency checks at all. That is correct behaviour for liveness — an orchestrator should not restart a process because a third-party dependency is degraded — but it means a healthy /health is not evidence the service can do useful work, and it must not gate a deploy.

The Weaviate dependency is covered as a per-request connect/close with a full behaviour matrix for the outage cases, including two asymmetries worth knowing: /search returns 200 {"results": []} when the collection is missing, so an unindexed corpus is indistinguishable from a genuine zero-hit query; and /index/message creates the collection on demand.

On cost controls, the honest answer is that there are none, so the doc records their absence as a known operational risk rather than describing an intended design. There is no rate limiting, no authentication, no max_tokens, no input size cap, no caching, and no retry/backoff — so any party with network reach to the service can spend against the OpenAI account. The deployment-level mitigations required until controls exist in the application are listed, along with a numbered risk table.

apps/ai_agent/docs/concepts-prompts-and-models.md — #585

Each prompt is reproduced verbatim from main.py — byte-identical, including indentation, so a diff against source is meaningful — alongside the behaviour it is designed to produce.

Models are documented per endpoint with guidance on changing one safely. The important distinction is that swapping a chat model is a reversible code edit, while swapping the embedding model is a corpus migration: text-embedding-3-small appears on both the write and read paths, vectors from different models are not comparable, and changing one side produces confident nonsense with no error.

Output parsing is documented per endpoint, with the transfer analyser's .get() defaults as the worked example. The two defaults deliberately fail in opposite directions — a missing flagged defaults to False (do not flag) while a missing confidence defaults to 0.0 (no confidence) — so a caller that gates on confidence catches both malformed cases, and a caller that reads flagged alone silently treats model failure as a clean transfer.

The privacy boundary is stated explicitly. /index/message sends the complete plaintext body of every indexed message to OpenAI, while its messageId, conversationId, and senderId never leave the system — content goes, metadata stays. The conversationId filter on /search is enforced inside Weaviate, not by the model.

apps/ai_agent/docs/testing.md — #584

Each conftest.py fixture: what it patches, what it returns by default, and why mock_openai targets main.OpenAI rather than openai.OpenAI (the name must be patched where it is used). Includes a worked example adding an endpoint test using the fixtures, and notes that the existing modules are not uniform — only test_chat.py uses them today, while the others patch inline.

Coverage configuration and how to read the report, using the real measured output rather than an invented sample.

The /index/message gap is recorded with a case table so a contributor can pick it up directly.

contracts/docs/contracts-errors.md — #580

Every panic and error path across the three contracts, grouped by function, separating authorization failures, validation failures, and state-machine violations (voting twice, approving after expiry, executing an unfinalised proposal).

Since none of the contracts define a #[contracterror] enum, there are no stable numeric codes and panic strings are not reliable at the ABI boundary. The doc therefore tells lib/soroban.ts callers to branch on the invocation stage — simulation failure, signature failure, submission failure, post-submission revert, timeout — rather than parsing messages, and to do pre-flight state reads so most failures become disabled controls instead of failed transactions. Notably, simulation catches nearly every deterministic panic before the user signs or pays a fee, and a confirmation timeout is not a failure and must never invite a retry. Cross-links apps/web/docs/api-soroban-client.md, and the events/testing/upgrades/resource-budget docs now on dev.

A few behaviours surfaced while tracing the code that are documented as findings, not fixed here — they are contract behaviour changes and belong in their own PR:

• group_treasury::list_proposals and get_pending_proposals iterate 1..=count, but ids are assigned from 0, so the first proposal ever created is never returned by either.
• proposals::finalize_expired_proposal can close an Active past-expiry proposal that would otherwise have Passed, discarding the tally and permanently blocking execution.
• proposals::execute_withdraw calls the treasury's admin-gated withdraw, so the proposals contract address must itself be the treasury admin or execution fails at the final step after every other check has passed.
• group_treasury::withdraw is admin-only and bypasses the proposal/threshold flow entirely.
• Removing a member does not clean up their votes, and shrinks the blocking_minority denominator for open proposals.

---

Verification

The ai_agent suite was run to check the documented behaviour against reality: 35 passed, 82% coverage, unchanged before and after the rebase onto dev. The coverage report and uncovered line range quoted in testing.md are the measured values, and 183-228 maps exactly to the body of index_message, confirming the documented gap.

I also wrote the /index/message cases from the gap table and ran them to confirm the guidance actually works. That surfaced a genuine error in my first draft: a missing OPENAI_API_KEY returns 503, not 500, on both Weaviate endpoints, because _openai_client() raises HTTPException(500, ...) inside a try whose except Exception as e catches it and re-raises as 503. The observed response is 503 {"detail": "500: OPENAI_API_KEY is not configured"}.

One thing worth a maintainer's eye: this contradicts apps/ai_agent/docs/configuration.md already on dev, which states these endpoints return 500 when Weaviate is reachable and 503 only when it is unreachable. I re-checked with a mocked-healthy Weaviate and the key removed — both /index/message and /search return 503 in that case too. operations.md documents the observed behaviour and carries a short note correcting the sibling doc; happy to instead patch configuration.md directly if you would prefer the correction to live there.

The probe tests were scaffolding and are not included — this PR is documentation only, and the test suite is untouched at its 35-passing baseline. Every relative link in the four documents was checked to resolve against files present on dev.