Skip to content

docs, apps: add a reports guideline and shape the full apps to it - #6

Merged
karalabe merged 1 commit into
dark-bio:mainfrom
karalabe:report-shape
Sep 17, 2026
Merged

karalabe merged 1 commit into
dark-bio:mainfrom
karalabe:report-shape

Conversation

@karalabe

Copy link
Copy Markdown
Member

An LLM writing an app from this repository had nothing telling it what a report should look like, and the seven full apps each printed a different shape. This adds the guideline and makes the apps its reference implementations.

  • docs/06-reports.md is the guideline. A report is the app's stdout up to 1 MiB, Markdown by convention, and it reads on a phone, as raw text and rendered. Title in Title Case, the finding straight under it, then Evidence, Method, Limitations and Sources. No app name, version or grant list, since the Ark reports those beside the report. Pick a voice and keep it; the examples are toys and read that way, with the serious register on record for heavier apps. Genomics vocabulary, never clinic vocabulary. Genotypes printed exactly as the file holds them. Plain Markdown only, with no images, HTML, footnotes, encoded content, dates or run ids.
  • AGENTS.md restates it in imperative form beside the build, run and check commands, for agents working in a checkout.
  • Every full app prints the shape, data access untouched: cilantro-soapiness (the page's sample, its exact output), drunk-o-type, bitter-meter, powerhouse-of-the-cell, vcf-roll-call, motif-finder and fortune-cookie. Each keeps its voice, tiers and figures; what changed is the order, the finding first with its value stated, per-allele evidence tables with positions, and numbered sources. The minis stay bare on purpose.
  • Apps that print coordinates now grant v1/genome/reference and read build, so positions carry the assembly rather than an assumed label. The two narrow fixture roots gain reference/build so those apps still run there.
  • The README and 01-app-model.md point at the new page.

The reference grant puts the stored reference genome on the approval screen of a one-variant app, and needs the reference slot filled on the Ark. The guideline says so, and the demos take that trade.

@karalabe
karalabe merged commit 29dc2d5 into dark-bio:main Sep 17, 2026
3 checks passed
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