STARTER_EXAMPLES.md

# Starter example portfolio and LSC-109 qualification

`starter-examples.json` is the machine-readable source of truth for this document, the marketplace manifest, shipped skill guidance, validators, and installed-host evidence tests. The final portfolio deliberately contains one annotated Sequence workflow, one true multi-record Alignment workflow, and one real-read QC workflow.

The historical [LSC-109](https://linear.app/openai/issue/LSC-109/sequence-and-alignment-viewer-qualify-every-refreshed-starter-example) clean-host qualification applies to Sequence Viewer version 0.1.26. Its `LSC_109_QUALIFICATION.md` report and `lsc-109-qualification.json` record remain with the canonical source. The current version, 0.1.43, has not received a separate clean-host qualification; the starter prompts, expected results, and procedure below remain useful guidance rather than evidence that version 0.1.43 has been qualified.

## Selection record

Codex owns public-data retrieval and workspace writes for every selected starter. It uses host-authorized research, network, and workspace tools against the exact official endpoints, verifies the catalog's stable identities, bounds, formats, and pinned digests, and records accurately Codex-authored provenance. Only after the requested workspace artifact is complete does Codex call `sequence.open_from_chat` exactly once with its exact absolute local path. This supported chat-opening route works when the plugin host does not expose MCP roots. The optional legacy acquisition tool is available only when the host independently authenticates an active plugin workspace root; it is never required for a starter or used as a rootless fallback.

The selected portfolio is:

1. ENA `DRR037765`, first 500 complete reads: bounded real-read quality and subset provenance.
2. Reviewed UniProtKB human RAS paralogs `P01116@SV1`, `P01111@SV1`, and `P01112@SV1`: protein alignment, conserved-core/reference mapping, distances/tree, and a workspace-published Newick result.
3. NCBI RefSeq `NC_001416.1`: annotated lambda cI/operator architecture and genetic-code-aware reverse-strand translation.

The prior Rfam `RF00360@15.1:seed` acquisition remains supported, but it is no longer a default starter. It is secure and compact, yet snoZ107/R87 is less recognizable than RAS and its C/D-box conservation is more nuanced than the old short prompt implied. Rfam `RF00008@15.1:seed` was the strongest RNA alternative (an iconic, bounded type-III hammerhead ribozyme); RAS won because it adds reviewed protein breadth and a clearer conserved-core versus hypervariable-tail question. Dense tRNA and SSU seed alignments were rejected for starter tree use.

## Exact marketplace prompts

These strings and their order are exact:

1. `Fetch ENA DRR037765 first 500 reads to active workspace; open and report live length range, GC, Q30, and subset provenance`
2. `Fetch UniProt P01116/P01111/P01112 alignment; map conserved motifs to KRAS, compute distances/tree, publish Newick to workspace`
3. `Fetch NCBI NC_001416.1 to active workspace; open it, map cI to OR1–OR3, and translate cI with code 11`

## Capability-to-example matrix

| Area         | Capability and selected example                                                                                                                     | Authoritative source and stable identity                                                                  | Bounds                                                                                                     | Expected scientific and visible state                                                                                                                                        | Artifact and provenance                                                                                                                                                                                | Failure behavior and tests                                                                                                                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sequence     | Annotated feature mapping and translation — NCBI lambda                                                                                             | NCBI EFetch; `NC_001416.1`, protein `NP_040628.1`                                                         | One GenBank record, at most 2 MiB; exactly 48,502 bases                                                    | Sequence mode; cI `complement(37227..37940)`, code 11; OR3 `37951..37967`, OR2 `37974..37990`, OR1 `37998..38014`; independently recomputed 237-aa reverse-frame translation | Codex-downloaded GenBank plus honestly Codex-authored provenance carrying the cI coding-sequence and protein SHA-256 values                                                                            | Accession, length, annotation, cI bases/translation, parser, network, size, disk, cancellation, and workspace drift fail before opening. Feature-location, translation, server, and installed-host tests own coverage.                   |
| Sequence     | Real-read QC — ENA subset                                                                                                                           | ENA `DRR037765`; authoritative filename, 127,526 compressed bytes, MD5 `81735432a6f578b332aae58cdbd95231` | 256 KiB metadata, 16 MiB compressed, 64 MiB decoded; first 500 of 967 parsed records                       | Sequence/FASTQ overview; 500 reads, 235,490 bases, 469–471 bp, GC 28.8%, Q30 95.4% from live state                                                                           | Canonical FASTQ SHA-256 `46bd72991d9c9c2bf64751e88e52548d852d5fa021da4815ee6f6517a51b18b9` plus honestly Codex-authored subset provenance                                                              | Metadata, filename, bytes, MD5, gzip, parse, subset, or workspace drift fails before opening. FASTQ, server, and installed-host tests own coverage.                                                                                      |
| Alignment    | Real multi-protein alignment, reference mapping, conservation, distance, and NJ tree — human RAS                                                    | Fixed UniProtKB FASTA endpoints; reviewed `P01116@SV1`, `P01111@SV1`, `P01112@SV1`                        | Three responses at most 32 KiB each; 189 aa each; fixed center-star scoring, 72,200 DP cells; 3×191 output | Alignment mode; P01116/KRAS reference; conserved P-loop, switch I/II, and NKXD region; divergent CAAX tails; distance matrix and graphical NJ tree                           | Source response/sequence digests plus actual-producer/score/warning provenance; 786-byte aligned artifact SHA-256 `cb32dd89ca7855f7666fbdf3f2ff926f935b1dbc9e7f57573f884dda7e59c68f`; workspace Newick | Source/version/digest/motif/alignment drift fails before opening. Codex workspace output never overwrites and accurately identifies its publisher. MSA analysis/tree, server, and installed-host tests own coverage.                     |
| Shared       | Codex-owned official-endpoint retrieval, validated workspace source, exact absolute chat-open path, one card/session — all three                    | Fixed catalog-pinned URLs and IDs; authorized research skills are optional                                | Existing network, decoded-byte, parser, artifact, command, and authorized-workspace quotas                 | Exactly one `sequence.open_from_chat` call, one opaque app resource, one visible viewer contribution, and one active session                                                 | Codex supplies the exact absolute path only to the chat-opening tool; the embedded app and tool result receive only opaque resources, relative provenance, and digests                                 | Retrieval, validation, or authorized-workspace failures leave no false viewer and never fall back to bundled data, guessed roots, foreign tasks, or plugin acquisition. Installed-host traces cover roots-positive and rootless opening. |
| Output       | Provenance-bearing create-new workspace output — RAS Newick                                                                                         | Verified opened RAS alignment and exact completed live NJ result                                          | Small Newick payload visible in the analysis result; ordinary authorized-workspace limits apply            | Completed tree remains visible; Codex creates the requested output and honestly Codex-authored provenance beside the source                                                  | Actual `sequence-viewer-guide-tree-v1` analysis engine, NJ, uncorrected p-distance, row identity, warning, source/output hashes, Codex publisher; no overwrite                                         | Existing output or sidecar, unauthorized destination, quota, disk, cancellation, or containment failures never overwrite. Optional plugin workspace publication additionally requires an independently authenticated source-bound root.  |
| Not selected | Edit-copy, annotation mutation, primer design, evidence/index/reference browsing, 512 MiB indexed opens, large Save As, and durable session restore | User-owned workspace data rather than a fixed starter source                                              | Existing feature-specific limits                                                                           | These remain product capabilities but would overload three concise examples                                                                                                  | Existing feature-specific provenance contracts                                                                                                                                                         | Focused regression and qualification suites remain authoritative; omission from starters is deliberate, not a product gap.                                                                                                               |

## Expected-results contracts

### ENA read QC

- Codex retrieves the exact ENA file report and archive through its authorized research/network tools, verifies the published filename, 127,526 compressed bytes, and MD5 `81735432a6f578b332aae58cdbd95231`, then parses exactly 967 complete source reads and writes only the first 500 canonical reads inside its authorized workspace.
- Verify the 480,372-byte selected FASTQ SHA-256 `46bd72991d9c9c2bf64751e88e52548d852d5fa021da4815ee6f6517a51b18b9`, write accurately Codex-authored subset provenance, and call `sequence.open_from_chat` exactly once with the verified file's exact absolute local path. Ordinary authorized tools must remain sufficient when optional Life Science Research skills are unavailable.
- Confirm one viewer/session in Sequence mode and read the FASTQ overview from live viewer state.
- Require exactly 500 reads, 235,490 total bases, a 469–471 bp range, GC `28.8%`, and Q30 `95.4%` at current UI precision.
- Verify the honestly Codex-authored provenance contains run accession, exact archive filename, compressed byte length, MD5, first-500 rule, artifact byte length, and SHA-256; do not describe it as a plugin-issued or signed receipt.
- Treat a changed ENA checksum, selected-read content, metric, or artifact hash as source drift requiring review. Retrieval time, HTTP cache metadata, and a collision-safe acquired-source suffix are allowed to vary.

### UniProt RAS alignment

- Codex retrieves the three fixed official FASTA responses, verifies their reviewed `SV=1`, 189-aa identities and sequence digests, and prepares the deterministic center-star aligned artifact in its authorized workspace.
- Require fixed KRAS/NRAS/HRAS input order, scores match `2`, mismatch `-1`, gap `-2`, exactly three rows and 191 columns, 786 bytes, and SHA-256 `cb32dd89ca7855f7666fbdf3f2ff926f935b1dbc9e7f57573f884dda7e59c68f`; accurately record the actual alignment producer, parameters, and exploratory warning in Codex-authored provenance.
- Call `sequence.open_from_chat` exactly once with the aligned FASTA file's exact absolute local path after all checks pass.
- Require one viewer/session already in Alignment mode. Set exact row `P01116` as reference.
- Map reference residues 10–17 (`GAGGVGKS`), 30–38 (`DEYDPTIED`), 60–76 (`GQEEYSAMRDQYMRTGE`), and 116–119 (`NKCD`). Confirm the GTPase core is strongly conserved and distinguish the C-terminal CAAX tails: KRAS `CIIM`, NRAS `CVVM`, HRAS `CVLS`.
- Run `sequence.run_analysis` for `distance-matrix` and for `build-tree` with `algorithm: "neighbor-joining"`. Expected p-distances are approximately `0.1315789474`, `0.1368421053`, and `0.1578947368` for KRAS/NRAS, KRAS/HRAS, and NRAS/HRAS respectively.
- Codex reads the exact completed, model-visible tree result and uses its own authorized workspace tools to create `RAS-P01116-P01111-P01112-NJ.nwk` and an adjacent honestly Codex-authored provenance file without overwriting either. A plugin `sequence.export_artifact` workspace destination is optional only when the host independently authenticates a source-bound workspace root; rootless success must not depend on plugin publication.
- Validate non-empty Newick with exactly the three accessions, its SHA-256, and accurate provenance. Record the actual `sequence-viewer-guide-tree-v1` analysis engine, neighbor joining, uncorrected p-distance, row identity, exploratory warning, source/output hashes, and Codex as publisher. Equivalent child ordering/display layout is allowed; missing leaves, changed input sequences/SV/engine, materially changed distances, overwrite, or falsely attributed provenance is not.
- State that this three-leaf uncorrected p-distance tree is exploratory, not a publication-grade RAS phylogeny.

### NCBI lambda cI switch

- Codex fetches exact RefSeq accession.version `NC_001416.1` through the official NCBI EFetch endpoint, validates the complete GenBank record and biological invariants, writes accurate Codex-authored source provenance, and calls `sequence.open_from_chat` exactly once with the verified source's exact absolute local path.
- Require exact accession.version `NC_001416.1`, one 48,502-base GenBank record, and one viewer/session in Sequence mode.
- Select the exact cI CDS and verify reverse strand, `complement(37227..37940)`, genetic code 11, and `NP_040628.1`. Before opening, Codex independently verifies cI coding-sequence SHA-256 `a51dec784e51f85a35d643a84820c89430b526cd9bf54a398b91c70045cc62e8` and 237-aa protein SHA-256 `ec5d954fd10be8c19c920e78badc5d9e9cc281f6801e2c5fde3803c9f133f580`. Verify the adjacent OR3, OR2, and OR1 annotations at the coordinates above.
- Call `sequence.run_analysis` for `translate` with start `37227`, end `37940`, frame `-1`, and `geneticCodeId: 11`; require a completed `sequence-viewer-translation-v2` result of 237 aa matching the annotated translation.
- Treat an accession, sequence length, cI/operator coordinate, code, strand, protein ID, or translation mismatch as failure. NCBI serialization, retrieval time, HTTP cache metadata, and a collision-safe acquired-source suffix may vary.

## LSC-109 clean-host qualification procedure

1. Build the marketplace bundle from the commit under qualification. Record commit SHA, plugin version, OS, model configuration, installed optional Life Science Research skills, and bundle digest.
2. Create a new empty, Codex-authorized workspace for each optional-skill and plugin-roots lane. Confirm no biological source, output, `codex-viewer-examples`, or smoke fixture exists before submission.
3. Install exactly one built Biological Sequence & Alignment Viewer bundle and submit each exact manifest prompt through the visible user entry point.
4. For every prompt, retain the complete model/tool/viewer trace. Assert that Codex fetched and validated the exact authoritative input using its own authorized tools, called `sequence.open_from_chat` exactly once with the verified artifact's exact absolute local path, and produced one opaque app source, one viewer card/contribution, one `viewerSessionId`, the expected mode, and no second open.
5. Execute every operation and scientific assertion in the contracts above from live viewer state. Do not infer results from filenames, this document, or direct source reads.
6. Validate the Codex-prepared artifact and accurately attributed provenance: authoritative URLs, stable identifiers, selection/derivation rule, byte counts, source/output digests, relative paths, actual author, and no fixture fallback.
7. For RAS, round-trip the Codex-created workspace Newick and sidecar: verify format, three-leaf set, non-zero size, SHA-256, create-new semantics, actual analysis-engine/parameter/source provenance, Codex as publisher, and one-session continuity. Separately test optional plugin publication only in an independently authenticated roots-positive lane.
8. Repeat the complete Codex-managed starter flow with optional Life Science Research skills unavailable and with the plugin MCP host exposing no workspace roots. The same official endpoints, authorized Codex workspace tools, exact absolute-path chat open, and Codex-owned Newick publication must succeed. An independently rooted legacy acquisition flow may be tested separately but must never become a starter prerequisite or rootless fallback.
9. Exercise representative failures without weakening the examples: offline/rate-limited/malformed response, identity/format/size/subset mismatch, output collision/quota failure, cancellation, and viewer retry/remount. Require actionable errors and no false viewer/artifact.
10. Capture fresh screenshots showing the exact prompt, visible viewer result, source identity, mode/state, analysis result, one card/session, and RAS output confirmation. Retain trace/log artifacts plus hashes and timings.
11. For the exact version being evaluated, validate and synchronize its `LSC_109_QUALIFICATION.md` report with its `lsc-109-qualification.json` record, including the final source binding, evidence links, and known limits. Historical version 0.1.26 evidence does not qualify version 0.1.43.

The historical version 0.1.26 record treats the clean committed revision used to execute that run as provenance. Its durable qualification subject is both the exact marketplace-bundle digest and a canonical digest of every tracked plugin file. Only the two self-referential evidence files above are excluded from the tracked-source digest; strict bundling recomputes both bindings. This content identity does not transfer the historical qualification to version 0.1.43 or to any other changed bundle.

The ordinary deterministic suite may use hash-pinned test data. The live official-endpoint suite and visible installed-host flow must remain separately runnable so public-network variability does not make presubmit flaky.