card: COBOL completer (not chatbot) + working examples; results ordered by pass@1

README.md

@@ -41,13 +41,16 @@ COBOL code generation.**
 All models evaluated on the **same harness**, greedy decoding, seed 0, GnuCOBOL compile+execute,
 official `{NAME}.TXT` scoring.
 
+Ordered by pass@1 (the benchmark). SkylarCobol is **#1 among all deployable models** — only the
+much larger reference teacher scores higher.
+
 | Model | Params | CSR (compile rate) | pass@1 |
 |---|---:|---:|---:|
+| *Claude Opus 4.8 (reference ceiling, not deployable)* | — | *96.6%* | *81.5%* |
 | **SkylarCobol-390M (this model)** | **390M** | **82.2%** | **5.5%** |
 | Qwen2.5-Coder-7B-Instruct | 7B | 6.2% | 2.1% |
 | CodeLlama-7B-Instruct | 7B | 6.8% | 0.7% |
 | StarCoder2-7B | 7B | 48.6% | 0.0% |
-| *Claude Opus 4.8 (reference ceiling)* | — | *96.6%* | *81.5%* |
 
 <sub>pass@1 = 8/146 problems solved. 95% binomial CI ≈ [2.4%, 10.5%] — low absolute, as expected for
 a 390M model on an execution benchmark; the point is the *relative* result vs the 7B baselines on the
@@ -97,33 +100,65 @@ DIVISION/LINKAGE structure, syntax, completion — where a human reviews the out
 This 390M is the **first step**. A larger model (~1B) with more code pretraining and longer context
 is in progress — that is the version intended to become a genuinely usable COBOL assistant.
 
-## Usage
+## How to use it — a COBOL **completer**, not a chatbot
 
-The easiest way — the `skylar` package (CLI + loader, auto-downloads the weights):
+**SkylarCobol-390M completes COBOL; it does not chat.** You give it a COBOL *stub* — a skeleton
+with the task written as comments, ending at `WORKING-STORAGE SECTION.` — and it writes the
+`WORKING-STORAGE` entries + `PROCEDURE DIVISION`. Do **not** prompt it with free-form natural
+language ("write me a program that…", and especially not in Italian): it will ramble, not code.
 
 ```bash
 pip install skylar
-skylar cobol --example          # complete a sample COBOL stub into a full program
-skylar chat                     # interactive REPL
-skylar generate --prompt "..."  # one-shot
+skylar cobol --example                      # the built-in demo stub
+skylar cobol --stub-file my_task.cbl --compile   # your own stub → completed + GnuCOBOL check
 ```
 
 ```python
 import skylar
 m = skylar.load("Sophia-AI/SkylarCobol-390M")
-print(m.complete_cobol(my_stub))     # reassembles a full, compilable program
+print(m.complete_cobol(my_stub))            # reassembles a full, compilable program
+```
+
+**✅ Tasks it handles reliably** — simple list / loop / accumulate / string work, e.g.
+`max_element`, `sum_to_n`, `strlen`, `incr_list`, `is_palindrome`, `flip_case`,
+`pairs_sum_to_zero`, `count_up_to`. Give it a stub shaped like these.
+
+**✅ Worked example — stub in → compilable program out** (real output, `cobc` accepts it):
+
+```cobol
+*> INPUT STUB (ends at WORKING-STORAGE SECTION.):
+       01 LINKED-ITEMS.
+           05 L-L OCCURS 3 TIMES INDEXED BY NI PIC S9(10).
+           05 RESULT PIC S9(10).
+      * Return maximum element in the list.
+      * >>> max_element([5, 3, -5])  ->  5
+       WORKING-STORAGE SECTION.
+
+*> SkylarCobol COMPLETES it:
+       01 WS-I PIC 9(4).
+       PROCEDURE DIVISION USING LINKED-ITEMS.
+           MOVE L-L(1) TO RESULT
+           PERFORM VARYING WS-I FROM 2 BY 1 UNTIL WS-I > 3
+               IF L-L(WS-I) > RESULT  MOVE L-L(WS-I) TO RESULT  END-IF
+           END-PERFORM
+           GOBACK.
+       END PROGRAM MAX-ELEMENT.
 ```
 
+**⚠️ Secondary mode:** a precise *technical* English instruction also works, e.g.
+`skylar generate --prompt "Write a COBOL PROCEDURE DIVISION that sums WS-NUMBERS into WS-TOTAL and displays it."` —
+but the stub format above is where it's strongest.
+
+**❌ Don't:** chat with it, prompt in natural Italian, or expect correct programs for hard tasks
+(pass@1 is 5.5% — it *compiles* ~82% of the time but its algorithmic reasoning is weak). Always
+review the output.
+
 `import skylar` also registers the architecture with 🤗 Transformers, so
 `AutoModelForCausalLM.from_pretrained("Sophia-AI/SkylarCobol-390M")` works too. The weights
 (`model.safetensors`) and `tokenizer.json` are standard; the architecture is a custom decoder
 (`NanoTransformer`, `model_type: nano-transformer` — Qwen3-style RMSNorm + RoPE + GQA + QK-Norm +
 SwiGLU), described in full in the accompanying paper.
 
-**Note** — this model expects a COBOLEval-style stub (a fixed-format skeleton with the task as
-comments, ending at `WORKING-STORAGE SECTION.`); `skylar`'s `complete_cobol` / `skylar cobol` wrap
-the prompt and reassemble the program for you.
-
 ## License & attribution
 
 Apache-2.0. IP: A. Ivanovitch (Sophia AI). Built in-house, no third-party pretrained weights.