lagora-cli 1.1.0

package/dist/skills/legato-agora-cli/SKILL.md

@@ -0,0 +1,556 @@
+---
+name: legato-agora-cli
+description: "Use this skill whenever an agent needs to work with the Legato Dev Agora CLI: search similar issues, report Legato kernel/lowering/fSIM issues, synthesize a minimal repro kernel when needed, fetch or inspect reported issues, download issue artifacts for debugging, run automatic lowering verification, add analysis/solution comments, update issue status, or handle site feedback. Trigger for Legato Agora, lagora, kernel issue report, lowering error reproduction, issue artifact download, site feedback, or language-team debugging workflows."
+---
+
+# Legato Agora CLI
+
+This skill lets an agent drive the `lagora` CLI end to end for Legato kernel issue workflows: issue search, issue reporting, issue lookup, artifact checkout, automatic lowering reproduction, structured debugging updates, and site feedback handling.
+
+Legato Dev Agora exists to automate the interface between Legato language users and language developers. The skill should make requests lightweight for kernel authors while preserving enough structure for language developers to triage, reproduce, resolve, and learn from more feedback.
+
+## First Decisions
+
+1. Choose the target. Commands run against the deployed board by default, so
+   normally you pass nothing:
+   - Another deployment, such as a local dev server: `--api-url <url>`, or set `LAGORA_API_URL`.
+   - Local or mounted issue store: `--store /path/to/issue-store`.
+2. Confirm the CLI:
+
+```bash
+lagora help
+```
+
+If `lagora` is not installed but this repo is available, run it from the repo with `./bin/lagora ...` after `npm install`.
+
+3. Log in before anything else when the target is the remote board. Every command except `lagora help` refuses to run without a verified login, so check first instead of discovering it through a failed request:
+
+```bash
+lagora whoami
+```
+
+## Login
+
+`lagora login` opens a browser and completes both the Keycloak sign-in and the activity-profile selection for that browser device. Nothing is typed into the CLI; it receives an opaque token bound to the API origin.
+
+```bash
+lagora login
+```
+
+Tell the user to finish the browser flow, then continue. Related commands:
+
+```bash
+lagora whoami   # who the saved login belongs to
+lagora tokens   # list and revoke this account's CLI tokens
+lagora logout   # revoke the token and clear it locally
+```
+
+If a command fails with either message below, stop and run `lagora login` again rather than retrying or working around it:
+
+- `Run \`lagora login --api-url <url>\` first` — no saved login
+- `CLI login expired; run \`lagora login --api-url <url>\` again` — the token was revoked or expired
+
+A saved login belongs to one API URL. Pointing `--api-url` at a different host requires logging in to that host; the CLI refuses to reuse the token across origins.
+
+Local `--store` workflows need no login, stay name-only, and do not receive server notifications.
+
+## Notifications
+
+The web board delivers in-app notifications through the authenticated browser session. The CLI is pull-based: it lists unread notifications and marks handled items read through the same server session cookie.
+
+At the start of an issue workflow, check unread notifications:
+
+```bash
+lagora issue notifications \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora
+```
+
+Use notification links to fetch or inspect the referenced issue, then mark handled notifications read:
+
+```bash
+lagora issue notifications read \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --notification <notification-id>
+```
+
+After a batch workflow, mark all handled notifications read only when every listed item has actually been handled:
+
+```bash
+lagora issue notifications read-all \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora
+```
+
+Do not expect notifications for actions performed by the same logged-in user. The board excludes the actor from their own notifications.
+
+## Announce A Verified Feature
+
+After a user-visible feature has passed its tests and manual QA and its production deployment is confirmed, publish a short site announcement:
+
+```bash
+LAGORA_ANNOUNCEMENT_TOKEN="<deployment-secret>" lagora announce create \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --title "Playground available" \
+  --body "Run a submitted kernel against a prepared SDK from the new Playground." \
+  --link /playground
+```
+
+Do not announce a local-only edit, a failed deployment, or an unverified feature. Never print, commit, or copy the announcement token into logs.
+
+## Inspect Or Update The Site's SDK Packages
+
+The site builds the Legato/HyperAccel SDK itself and follows upstream on a 12-hour timer. Use this when a Playground run fails on a missing or stale package, or when a new SDK version should be picked up now rather than at the next check.
+
+The token comes from **Settings → SDK → CLI access token**, where an admin issues one. Rotating replaces the old token; revoking closes the CLI routes entirely.
+
+Read the current state first — this reports whether a prepare is running, and why the last one failed:
+
+```bash
+LAGORA_SDK_TOKEN="<deployment-secret>" lagora sdk status \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora
+```
+
+```bash
+lagora sdk list --api-url ...          # prepared versions; --disk adds sizes
+lagora sdk log --api-url ...           # full build output of the last prepare
+```
+
+Trigger an update. This builds the upstream version when it is newer than anything prepared, then prunes all but the newest few:
+
+```bash
+LAGORA_SDK_TOKEN="<deployment-secret>" lagora sdk update \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --watch
+```
+
+A prepare compiles the SDK from source and takes over an hour; `--watch` polls until it settles and exits non-zero on failure. `--force` rebuilds the current version instead of stopping when upstream is already prepared — use it only to recover from a corrupted build, since it discards a working runtime's cache advantage. Never print, commit, or copy the SDK token into logs.
+
+## Report A New Issue
+
+Use this when the user has a failing kernel, error log, compile/lowering failure, or wants the language team to inspect a reproducible problem.
+
+Before creating a new report, search for similar open or resolved issues unless the user explicitly says to skip duplicate checking:
+
+```bash
+lagora search \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --query "CORE_IR lowering cgdma Xfer=0 receive_type" \
+  --limit 5
+```
+
+For a local issue-store:
+
+```bash
+lagora search --store /path/to/issue-store --query "lowering verifier request_load" --limit 5
+```
+
+If a likely duplicate exists, fetch or comment on the existing issue instead of filing a new one. If the match is only related, mention the related issue in the new report body.
+
+### Test a working-tree kernel in Playground
+
+When the user wants to test current code before deciding whether it is an
+issue, use the Playground CLI instead of `lagora report`:
+
+```bash
+lagora playground runtimes
+lagora playground run --kernel /path/to/kernel.py --sdk-name <prepared-runtime-name>
+lagora playground status --run <run-id>
+```
+
+Use `--legato <version> --sdk <version>` instead of `--sdk-name` when the user
+names a published runtime pair. Use `--mode fsim` only when a value run is
+required. Preserve the returned run id.
+
+If the run demonstrates a reportable problem, submit the exact tested source
+and worker log without rebuilding the bundle by hand:
+
+```bash
+lagora playground report \
+  --run <run-id> \
+  --title "<short symptom>" \
+  --description "<what the run demonstrated>" \
+  --tags lowering,regression
+```
+
+This keeps the issue linked to the run by source hash. Do not edit the kernel
+between `run` and `report`; start another run for edited source.
+
+Required inputs:
+
+- kernel file path
+- short title
+- reporter/author name
+
+Useful optional inputs:
+
+- error log path
+- tags, comma-separated
+- SDK root and Python for automatic lowering
+- kernel function name when the module has multiple `@legato.compile` functions
+
+Write a concise report body to `/tmp/legato-agora-report.md`. Use Korean by default, but preserve exact command names, pass names, identifiers, and error messages in their original form.
+
+When the user already supplied the failing kernel, preserve it as evidence even
+if it has its own launcher. Do not rewrite away the bug just to satisfy the
+Playground harness. The strict harness contract below applies to kernels this
+skill generates or adapts specifically for automated Playground verification.
+
+```bash
+lagora report \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --kernel /path/to/kernel.py \
+  --log /path/to/error.log \
+  --title "lowering failure in matmul kernel" \
+  --reporter "agent" \
+  --description-file /tmp/legato-agora-report.md \
+  --tags lowering,repro
+```
+
+If there is no log, omit `--log`. For local archival instead of API upload:
+
+```bash
+lagora report --store /path/to/issue-store --kernel /path/to/kernel.py --title "..." --reporter "agent" --description-file /tmp/legato-agora-report.md
+```
+
+## Auto-Generate A Repro Kernel
+
+Use this only when the user asks for automation or no kernel artifact is available but the failure description/log contains enough shape, dtype, operation, and Legato API context to create a plausible minimal repro.
+
+**Start from `reference/kernel-with-golden.py` in this skill.** It is a complete,
+verified harness-driven submission. Copy it and change three things: `inputs`,
+`golden`, and `kernel`. Do not write a launcher from memory; the site harness
+owns stage selection, stage output directories, lowering-only launch behavior,
+and the value verdict.
+
+Rules:
+
+- Put generated files under `/tmp/lagora-repro-<short-name>/`.
+- Name the file `generated_repro_kernel.py`.
+- Keep the reference's module-level structure. The site reads `inputs`, `SHAPES`, `golden`, and the decorated kernel by name, so do not rename them.
+- Write tensor shapes as **literals** in the annotations and in the kernel body. legato recompiles that source where module constants are not in scope and fails with `error[LE0003]: Undefined variable`.
+- Keep the kernel at module level; legato reads its source with `inspect.getsource`.
+- Do not add a custom `main`, `run_lowering`, or `legato.session`. In particular, never add a hardcoded `OutputType.BINARY`; doing so bypasses the site harness and can put `.bin` files under every lowering stage.
+- If the kernel leaves a dimension dynamic, declare `SHAPES = {"a": (4096, 256), ...}` to pin the size the failure needs. Otherwise the site substitutes one and says so in the log.
+- `inputs` returns values keyed by parameter name. Supply the values the failure actually happens on; without them the site uses seeded random data, which is reproducible but may be a different case.
+- `golden` is the reference answer in plain torch. Write it only when the intended result is actually known. Without it the kernel still lowers and runs; the site reports the value check as unavailable, which is honest. **Never write a `golden` that returns the kernel's own output** -- that manufactures a pass and hides the bug being reported.
+- State in the report that the kernel is agent-generated and may need confirmation.
+
+Before reporting, ask production dispatch to validate the generated file:
+
+```bash
+lagora playground validate --kernel /tmp/lagora-repro-case/generated_repro_kernel.py
+```
+
+The command must accept the file. If production dispatch says the file has its
+own launcher, remove the launcher/session and restore the reference shape
+before submission.
+
+Then report it normally:
+
+```bash
+lagora report \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --kernel /tmp/lagora-repro-case/generated_repro_kernel.py \
+  --title "agent-generated lowering repro for <symptom>" \
+  --reporter "agent" \
+  --description-file /tmp/legato-agora-report.md \
+  --tags lowering,generated-repro
+```
+
+## Run Lowering Reproduction Automatically
+
+For a new report, ask the CLI to run staged lowering after storing the issue:
+
+```bash
+lagora report \
+  --store /path/to/issue-store \
+  --kernel /path/to/kernel.py \
+  --log /path/to/error.log \
+  --title "lowering failure" \
+  --reporter "agent" \
+  --description-file /tmp/legato-agora-report.md \
+  --auto-lowering \
+  --sdk-root /root/workspace/hyperaccel-sdk \
+  --python /root/workspace/hyperaccel-sdk/.venv/bin/python \
+  --stages MLIR,CORE_IR,BACKEND_IR,ASM,BINARY
+```
+
+For an existing issue:
+
+```bash
+lagora verify \
+  --store /path/to/issue-store \
+  --issue <issue-id> \
+  --kind lowering \
+  --mode real \
+  --sdk-root /root/workspace/hyperaccel-sdk \
+  --python /root/workspace/hyperaccel-sdk/.venv/bin/python \
+  --stages MLIR,CORE_IR,BACKEND_IR,ASM,BINARY
+```
+
+Add `--kernel-function <name>` when needed. Use `--mode plan` only when the user wants a recorded plan/skipped verification instead of real execution.
+
+## Fetch, Inspect, And Download Issue Files
+
+Use `fetch` to download the full issue bundle and artifacts for debugging. Fetching an `open` issue is also a response signal: it marks the issue `investigating` so the reporter can see that a language developer or agent has started looking at it.
+
+```bash
+lagora fetch \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --issue <issue-id> \
+  --author "agent" \
+  --out ./lagora-issues/<issue-id>
+```
+
+For local issue-store:
+
+```bash
+lagora fetch --store /path/to/issue-store --issue <issue-id> --author "agent" --out ./lagora-issues/<issue-id>
+```
+
+Use `issue fetch` when you need a quick textual or JSON inspection:
+
+```bash
+lagora issue fetch --store /path/to/issue-store --issue <issue-id>
+lagora issue fetch --store /path/to/issue-store --issue <issue-id> --format json
+```
+
+After checkout, inspect:
+
+- `issue.json` for status, tags, artifacts, occurrences, comments, and verification runs
+- `description.md` for the original report
+- downloaded kernel/log artifacts for reproduction
+- `verification-output-*.log` for lowering stage failures
+
+Do not paste large logs into chat. Summarize the relevant stage, stack frame, and error lines.
+
+## Search Existing Issues
+
+Use search whenever a user asks whether a failure is known, asks for similar issues, or before filing a new report. Search uses local similarity scoring over issue title, description, tags, comments, and artifact filenames; it is not proof of duplication.
+
+Remote board:
+
+```bash
+lagora search \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --query "matmul lowering verifier total physical bytes" \
+  --limit 10
+```
+
+Local issue-store:
+
+```bash
+lagora search --store /path/to/issue-store --query "runtime loop cgdma warning"
+```
+
+Search output gives issue id, status, score, title, and match reasons. Use it this way:
+
+- High score plus same failed stage and diagnostic: likely duplicate; fetch the issue and add an occurrence/comment.
+- Same operator family but different stage or diagnostic: related; cite it but do not block a new report.
+- Resolved match: tell the user the fixed version/workaround if recorded, then compare with their SDK commit before closing.
+
+## Structured Comments And Status
+
+Comments should be normalized because most users are expected to work through agents and this skill. Always prefer a structured comment over free-form prose.
+
+The first block must be YAML frontmatter for machines. The site may hide this block, so do not rely on it for human communication. The markdown body after the frontmatter must read like a real Korean comment written for a person, not like formatted YAML repeated in prose.
+
+Hidden frontmatter exists to let agents, CLI commands, and the site automate four decisions:
+
+- status transition evidence: whether a comment should move or justify `investigating`, `resolved`, `needs_info`, `duplicate`, or `blocked`
+- next-action routing: whether the reporter, language team, agent, or nobody should act next
+- similarity handling: whether this issue is canonical, duplicate, related, or shares the same root cause
+- resolution guidance: whether a fixed version, commit, workaround, or verification result is strong enough to guide future reports
+
+Use these comment categories:
+
+- `triage`: first classification and likely owner/component
+- `reproduction`: reproduction succeeded or failed
+- `root_cause`: suspected or confirmed cause
+- `workaround`: user-facing workaround
+- `fix_candidate`: concrete code or design direction
+- `verification`: verification result and evidence
+- `release_note`: fixed version, commit, or upgrade guidance
+- `needs_info`: missing reporter input blocks further diagnosis
+
+Use this body shape for `lagora comment --body`. Keep tag values in English. Required v1 fields are `kind`, `stage`, `status_intent`, `reproduced`, `confidence`, and `next_action`. Delete unknown optional keys instead of leaving blank keys. For `stage`, use a workflow value when describing progress and a compiler/runtime value when identifying a failure location.
+
+````markdown
+---
+kind: triage | reproduction | root_cause | workaround | fix_candidate | verification | release_note | needs_info
+stage: report | fetch | reproduce | diagnose | patch | verify | release | MLIR | CORE_IR | BACKEND_IR | ASM | BINARY | fsim | compile | runtime | unknown
+status_intent: investigating | resolved | needs_info | duplicate | blocked | none
+reproduced: true | false | unknown
+confidence: low | medium | high
+next_action: reporter | language_team | agent | none
+---
+
+## 요약
+핵심 판단을 사람이 바로 이해할 수 있는 자연스러운 한국어 댓글로 1-2문장 적습니다.
+
+## 근거
+- 확인한 artifact, 로그 줄, stage, command를 짧게 적습니다. YAML 키를 그대로 나열하지 마세요.
+
+## 다음 액션
+- 누가 무엇을 하면 되는지 댓글 문장으로 적습니다.
+````
+
+Optional keys when known: `issue_relation`, `canonical_issue_id`, `related_issue_ids`, `similarity_basis`, `duplicate_of`, `fixed_version`, `fixed_commit`, `upgrade_advice`, `affected_versions`, `verification_scope`, `verification_result`, `artifact_ids`.
+
+Visible comment body rules:
+
+- Write Korean prose for a human reader; never list frontmatter keys again in the body.
+- Say what changed, what evidence supports it, and what happens next.
+- State uncertainty explicitly; do not mark guesses as confirmed.
+- Keep logs short: quote only the decisive line or artifact name.
+
+Compact body examples:
+
+- `reproduction`: "첨부 artifact로 동일한 CORE_IR lowering 실패를 재현했습니다. 다음으로 reduction axis가 깨지는 pass를 좁히겠습니다."
+- `needs_info`: "현재 로그만으로는 실패 stage를 확정하기 어렵습니다. reporter가 실행 명령과 전체 lowering 로그를 추가해야 합니다."
+- `release_note`: "이 문제는 v1.4.2에서 해결된 패턴과 일치합니다. 같은 환경이라면 v1.4.2 이상으로 올리는 것을 권장합니다."
+
+Post debugging findings with `--kind analysis` unless the comment contains a user-actionable fix or confirmed resolution:
+
+```bash
+cat > /tmp/legato-agora-comment.md <<'EOF'
+---
+kind: reproduction
+stage: CORE_IR
+status_intent: investigating
+reproduced: true
+confidence: medium
+next_action: language_team
+---
+
+첨부 artifact로 동일한 CORE_IR lowering 실패를 재현했습니다.
+다음으로 reduction axis가 깨지는 pass를 좁히겠습니다.
+EOF
+
+lagora comment \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --issue <issue-id> \
+  --author "agent" \
+  --kind analysis \
+  --body "$(cat /tmp/legato-agora-comment.md)"
+```
+
+Use `--kind solution` only when the comment contains a concrete fix, workaround, or resolved guidance. A `solution` comment moves the issue toward `resolved`; do not use it for speculative root-cause notes.
+
+Update status when the investigation state changes:
+
+```bash
+lagora status \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --issue <issue-id> \
+  --author "agent" \
+  --status investigating
+```
+
+Allowed statuses: `open`, `investigating`, `resolved`, `deferred`, `cancelled`.
+
+Status guardrails:
+
+- `open`: no one has started handling it.
+- `investigating`: a language developer or agent has fetched artifacts or started analysis. `lagora fetch` automatically performs this transition for open issues.
+- `resolved`: only after a confirmed fix, workaround, or upgrade path is recorded. Prefer `verification_result: passed` or a known `fixed_version` before running `lagora status --status resolved`.
+- `deferred`: valid issue, but intentionally not being handled now.
+- `cancelled`: invalid, misfiled, or not actionable as a Legato language issue.
+- `status_intent` is evidence, not a command. Do not change issue status if the comment is speculative or asks for missing reporter input.
+
+## Similarity And Duplicate Guidance
+
+The board can group exact or similar reports by fingerprint/kernel evidence. Treat similarity as a decision aid, not as proof.
+
+When reporting a new issue:
+
+- Run `lagora search` with the strongest diagnostic terms, stage, operator name, and any unique warning/error text.
+- Check for similar unresolved issues when the same kernel, checksum, failure stage, or diagnostic signature appears.
+- If a similar unresolved issue exists, prefer adding an occurrence or comment to that issue instead of creating a new issue.
+- If a similar resolved issue exists, do not hard-block by default. Tell the user which issue appears related, what fixed version or workaround was recorded, and ask whether to submit anyway if the current environment/version differs.
+- Only recommend hard-blocking a report for a hard duplicate: same fingerprint, or same kernel checksum plus same failed stage and diagnostic signature.
+- Treat same stage plus similar diagnostic as `related`; treat same operator family only as a weak signal.
+
+When resolving an issue:
+
+- Look for grouped occurrences and related issue IDs before marking only one report resolved.
+- If the same fingerprint group is covered by the same fix, update the canonical issue and leave a structured `release_note` or `verification` comment that references the affected reports.
+- If the match is only approximate, do not bulk-resolve. Add related links and keep separate statuses.
+
+## Site Feedback Inbox
+
+Use site feedback for requests about the Lagora site itself: UI layout, navigation, settings, workflow friction, missing controls, confusing wording, or agent/CLI affordances. Do not use it for Legato kernel bugs; those should be ordinary issues.
+
+List or fetch open feedback:
+
+```bash
+lagora feedback fetch \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --status open
+```
+
+Local issue-store:
+
+```bash
+lagora feedback list --store /path/to/issue-store
+```
+
+Resolve after implementing or intentionally declining:
+
+```bash
+lagora feedback resolve \
+  --api-url https://legato-dev-agora.hyperaccel.net/legato-dev-agora \
+  --id <feedback-id> \
+  --author "agent"
+```
+
+When acting on feedback:
+
+- Fetch/list first and quote the feedback id in your work notes.
+- If it maps to a code change, implement and verify the change before resolving.
+- If it is vague, leave it open and ask for clarification through the normal conversation; do not mark it resolved just because it was read.
+
+## Report Body Template
+
+````markdown
+## TL;DR
+무엇이 실패했는지 한두 문장으로 요약합니다.
+
+## 실패 지점
+- Stage: `lowering | fsim | compile | runtime | unknown`
+- 의심 pass/component: `알고 있으면 작성`
+- 영향도: `lowering 차단 | 결과 불일치 | flaky | 확인 요청`
+
+## 재현 방법
+```bash
+실행한 명령 또는 재현 명령
+```
+
+## 기대 결과
+정상이라면 어떤 결과가 나와야 하는지 적습니다.
+
+## 실제 결과
+실제로 어떤 실패가 발생했는지 적습니다.
+
+## 핵심 에러
+```text
+짧은 핵심 에러 5~20줄. 원문 에러 메시지는 번역하지 않습니다.
+```
+
+## 언어팀 확인 요청
+- 의심되는 원인
+- 확인해줬으면 하는 부분
+- 관련 커널 패턴
+
+## 첨부/자동 수집 정보
+- 커널 파일과 전체 로그는 artifact로 첨부됩니다.
+- Legato 버전, git 상태, checksum, OS/Python/Node 정보는 CLI가 자동 수집합니다.
+````
+
+## Safety And Quality
+
+- Do not run destructive commands.
+- Do not execute arbitrary kernels unless the user asks for reproduction or verification.
+- Do not include credentials, tokens, secrets, or unrelated private paths in reports/comments.
+- Prefer absolute paths for local reproduction traceability.
+- If a command fails, report the exact command attempted and the important error lines.
+- When using generated repro kernels, label them as generated and avoid overstating certainty.

package/dist/skills/legato-agora-cli/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Legato Agora CLI"
+  short_description: "Report, fetch, and verify Legato issues"
+  default_prompt: "Use $legato-agora-cli to report or inspect a Legato kernel issue with the lagora CLI."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/legato-agora-cli/reference/kernel-with-golden.py

@@ -0,0 +1,84 @@
+"""Reference submission for Legato Dev Agora. Copy this file and change three things.
+
+  1. `inputs` -- the values the failure happens on. Both the kernel and the
+     reference are given exactly these, so a bug that only reproduces on
+     particular numbers actually reproduces.
+  2. `golden` -- the same computation in plain torch. This is what the site
+     checks the kernel against, so keep it simple enough to be obviously right.
+  3. `kernel` -- the Legato function being reported.
+
+Nothing else is required. The site allocates the tensors, places them, runs the
+session and reports the verdict; shapes, dtypes and device layouts are all read
+off the annotations below. In particular, do not add `legato.session`, a
+launcher, or a `__main__` block. Those bypass the site harness that selects each
+lowering stage and maps it to the matching artifact directory.
+
+Two rules that are easy to get wrong:
+
+  * Write shapes as literals in the annotations and in the body. legato
+    recompiles this function's source on its own, where module constants are not
+    in scope, and reports `error[LE0003]: Undefined variable`.
+  * Keep the kernel at module level. legato reads its source with
+    inspect.getsource.
+
+If the kernel leaves a dimension dynamic, add `SHAPES = {"a": (4096, 256), ...}`
+to pin the size the failure needs; otherwise the site substitutes one and says
+so in the log. Without `inputs` the site uses seeded random data, which is
+reproducible but is not the case being reported -- supply it whenever the
+failure depends on the values. Without a `golden` the kernel still lowers and
+runs; the site just reports the value check as unavailable rather than claiming
+a pass it cannot support.
+
+Verified end to end against a prepared runtime: lower=pass, fsim=pass,
+value=pass, max_abs_diff=0.067560.
+"""
+# type: ignore
+# ruff: noqa
+from __future__ import annotations
+
+import legato
+import legato.model.bertha as bertha
+
+RTOL = 0.05
+ATOL = 0.2
+
+
+def get_bertha(ctx):
+    return bertha.Bertha(ctx, "bertha", 32, False, 8, 128 * 1024**3)
+
+
+def inputs():
+    """The values to run on. Shapes must match the kernel's annotations."""
+    import torch
+
+    torch.manual_seed(0)
+    return {
+        "a": (torch.rand(20, 256) * 2 - 1).to(torch.bfloat16),
+        "b": (torch.rand(256, 128) * 2 - 1).to(torch.bfloat16),
+    }
+
+
+def golden(a, b):
+    import torch
+
+    return torch.matmul(a.float(), b.float())
+
+
+@legato.compile(backend=get_bertha, param_kinds={"a": "universal", "b": "top", "out": "core"})
+def kernel(
+    a: legato.get_model().tensor_type(legato.types.float("bfloat16"), (20, 256), "shared_dram"),
+    b: legato.get_model().tensor_type(legato.types.float("bfloat16"), [256, 128], "mpu_dram"),
+    out: legato.get_model().tensor_type(legato.types.float("bfloat16"), (20, 128), "shared_dram"),
+):
+    device = legato.get_context().get_device()
+
+    with device.get_top():
+        legato.tensor.request_load(a, device.get_core(0), "sram")
+        legato.tensor.request_load(b, device.get_core(0), "mpu_buffer")
+
+    with device.get_core(0):
+        weight_type = legato.get_model().tensor_type(legato.types.float("bfloat16"), [256, 128], "mpu_weight")
+        loaded_a = legato.tensor.receive(a, 0, "sram")
+        loaded_b = legato.tensor.receive_type(weight_type, 0, None, "mpu_buffer")
+
+        legato.tensor.memcpy(out, loaded_a @ loaded_b)