The Atlas Donna's documentation, bound to its code
147 documents

The lq-ai contract & upstream loop

Donna implements no legal-AI logic — it consumes a contract. This is what happens when the contract isn't enough: file an ask, relay it, bump the pin.

8. The upstream-request workflow (when the API isn't enough)

You will hit gaps where lq-ai doesn't expose what a feature needs. Do not work around it by editing the submodule or coupling to internals. Instead:

  1. Write the ask to docs/upstream-requests/lq-ai-<short-name>.md — the gap, the proposed contract, and why. Use absolute file paths if the lq-ai maintainer works in a different checkout.
  2. The human relays it to the lq-ai maintainer session.
  3. When the fix merges, bump the pin:
    cd vendor/lq-ai && git fetch && git checkout <sha>
cd ../.. && npm run gen:api                      # regenerate types
docker compose up -d --build api arq-worker ingest-worker donna-web   # migrations run on api boot
    Then verify the merged contract in src/lib/api/backend.d.ts — the merged shape wins over the ask — record the bump in docs/decisions/lq-ai-pin.md, and build the consuming slice.

docs/decisions/lq-ai-pin.md is the running log of every pin bump and what it unblocked — read its top entry to know what backend you're on (currently c4d4482).