Skip to content

docs: two device-recorded demos, Apache-2.0, and four claims the code did not support - #19

Merged
karolkulesza merged 1 commit into
mainfrom
docs/readme-demo-gifs
Aug 20, 2026
Merged

karolkulesza merged 1 commit into
mainfrom
docs/readme-demo-gifs

Conversation

@karolkulesza

@karolkulesza karolkulesza commented Aug 19, 2026 •

Copy link
Copy Markdown
Owner

What

The README opens on a demo GIF instead of an ASCII trace, and picks up a licence. Along the way, four claims that the codebase does not support were corrected.

The GIFs

Both are real runs on an iPad in airplane mode against the real 2.59GB artifact. Trimmed past the launch animation, sped 3× through the Diagnosing… gap (the deliberate no-spinner window), and ended on the payoff frame.

File Scenario What it proves
docs/demo-out-of-stock.gif (hero) 2 · the empty shelf E-305 retrieved from symptoms alone, both tools fire, and the prose agrees with the warehouse — "0 units in stock at Aisle 1, Shelf C" — instead of inventing a quantity next to a correct tool result
docs/demo-work-order.gif (design decision 2) 1 · four fields 4 of 4 filled, including 1.5 derived from "an hour and a half", which nothing in the schema asks for

The previous opening trace showed both tool calls and a 4-of-4 fill including an inventory hit. No single run produces that — when the technician has already replaced the part, no parts are required, so the MUST clause correctly never fires. It was a composite; it is gone.

Claims corrected

  • "Downloads are resumable" — they are not. No Range header exists in model_downloader.dart; model_provisioner.dart:558 and model_storage.dart:181 both document that an interrupted transfer carries no resumable state and is swept; and docs/model-provisioning.md already listed resume under what this deliberately does not do. The claim appeared in three places in the README and is fixed in all of them.
  • Four ## Not wired into the app sections survived the docs/ split verbatim, still saying Task 1.11 owed the wiring. It shipped. Deleted from agent-tools, retrieval-and-prompt, tool-call-guard, agent-loop.
  • "The model has never been observed calling record_work_order_fields" — it does, unprompted, on both runs above. Replaced with the evidence, plus the one defect the same runs exposed: on scenario 2 it sent two values under field names the form does not have, and the panel said so.
  • Camera OCR / barcode scanning removed from the Status table.

Also

  • Apache-2.0. LICENSE was Not yet specified. Text copied verbatim from a pub-cache copy (md5 3b83ef96387f14655fc854ddc3c6bd57, cross-checked byte-for-byte against a second package) with only the copyright line filled in. The README notes that the Gemma weights are governed by the Gemma terms, not by this licence.
  • A "How this was built" section that owns the AI-assisted workflow explicitly rather than leaving it implied by commit trailers.
  • ledgers/ ignored — local review ledgers and mutation harnesses, and the source of all 40 flutter analyze infos.

Verification

  • flutter test — 1179 passed, 7 skipped
  • flutter analyze — clean on tracked code
  • All 16 docs/ links resolve; no dangling anchors from the deleted sections
  • GIF first/last frames verified by extracting them back out of the finished files

Docs, a licence file, and two GIFs only — no Dart changed.

… did not support

The README now opens on a GIF instead of an ASCII trace, and both GIFs are runs
that actually happened on an iPad in airplane mode against the real 2.59GB
artifact — not composites.

- demo-out-of-stock.gif (hero): symptoms alone retrieve E-305, both tools fire,
  and the *prose* agrees with the warehouse ("0 units in stock at Aisle 1,
  Shelf C") rather than inventing a quantity beside a correct tool result.
- demo-work-order.gif (design decision 2): 4 of 4 fields, including 1.5 derived
  from "an hour and a half", which nothing in the schema asks for.

The old opening trace showed both tool calls *and* a 4-of-4 fill including an
inventory hit. No single run produces that: when the technician has already
replaced the part, no parts are required, so the MUST-call clause correctly never
fires. It was a composite, and it is gone.

Claims corrected:

- "Downloads are resumable" — they are not. No Range header exists in
  model_downloader.dart, and model_provisioner.dart:558 and model_storage.dart:181
  both document that an interrupted transfer carries no resumable state and is
  swept. docs/model-provisioning.md already listed resume under what this
  deliberately does not do. Fixed in all three places the claim appeared.
- Four "Not wired into the app" sections survived the docs/ split verbatim and
  still said Task 1.11 owed the wiring. It shipped. Deleted.
- "The model has never been observed calling record_work_order_fields" — it does,
  unprompted, on both runs above. Replaced with the evidence, and with the one
  defect the same runs exposed: on scenario 2 it sent two values under field names
  the form does not have.
- Camera OCR / barcode scanning removed from the Status table.

Also: Apache-2.0 (LICENSE was "Not yet specified"), a "How this was built" section
that owns the AI-assisted workflow rather than leaving it to the commit trailers,
and ledgers/ ignored.

Known and deliberately not fixed here: the "Grounded in" banner renders
job.retrieval!.entries, the router's uncapped result, while compile() sends only
maxDocuments (2). Both GIFs therefore name a third document the model never saw.
That is a UI bug, not a docs bug, and it needs a design decision — show the capped
set, or show all and mark the withheld — so it is filed rather than patched.

Co-Authored-By: Claude <noreply@anthropic.com>
@karolkulesza
karolkulesza merged commit 4dfcb7e into main Aug 20, 2026
1 of 2 checks passed
karolkulesza added a commit that referenced this pull request Aug 20, 2026
docs: two device-recorded demos, Apache-2.0, and four claims the code did not support
@karolkulesza
karolkulesza deleted the docs/readme-demo-gifs branch August 21, 2026 14:05
karolkulesza added a commit that referenced this pull request Aug 22, 2026
docs: two device-recorded demos, Apache-2.0, and four claims the code did not support
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant