feat: make help, lint/fmt targets, a Render test, and AGENTS.md by moul · Pull Request #8 · gnolang/getting-started

moul · 2026-09-17T12:09:33Z

Follow-up to #7, aimed at #1 ("make this the easiest way to try Gno"). The repo
stays small, and the change is mostly subtraction: anything docs.gno.land
already explains is now a link rather than a paragraph.

Makefile as the single entry point. make with no argument lists every
target (the self-documenting ## + awk idiom). Added lint and fmt, which
the toolchain already provides and this repo never exposed. GNO ?= gno and
GNODEV ?= gnodev so a toolchain that is not on PATH can be pointed at. CI
runs make test / make lint instead of its own copies of the commands, so
local and CI cannot drift.

  help     list the available targets
  install  build the gno toolchain into $HOME/.gno/bin
  dev      run a local chain + web UI on http://localhost:8888, reloading on save
  test     run the tests
  lint     catch what only the chain would otherwise catch
  fmt      format every .gno file in place

Links instead of copies. README and AGENTS.md now point at the official
pages for installing, gnodev, realms and interrealm, testing, Go/Gno
compatibility, stdlibs, effective Gno, editor setup, and deploying. What they
replace was either a duplicate of the docs or subtly wrong: review caught bad
claims about map iteration order, ufmt flags, and "Render is the realm's
entire public surface". Duplicated prose is how those get written in the first
place.

A test for Render. hello_test.gno gets a TestRender that asserts the
message shows up, deliberately loose so that editing Render (which the repo
actively invites) does not turn CI red.

AGENTS.md (52 lines) + a one-line CLAUDE.md. What the repo is, the
commands, an index of the docs pages that matter, and the two tools worth
having: gnoverse/gno-mcp (MCP server
plus agent skills for gno.land) and
gnoverse/gnopls (language server).

hello.gno no longer hardcodes /r/example/hello in the page it renders,
so a reader who re-points module does not ship a button that calls a realm
they do not own.

Next Steps links the monorepo's
examples/, then
moul/gno-contracts as the "what this grows into" reference, and
gnoverse/awesome-gno for everything else. The gnolang/repo-template link is
gone: every one of its three Make targets fails on the current toolchain.

Verified on gno master: make test ok, make lint clean, gno fmt -diff . no
diff, and every link in README and AGENTS.md returns 200.

…po-template link

davd-gzl

I will follow with AI comments I verified.

davd-gzl · 2026-09-17T14:49:56Z


 1. Clone this repository:

        git clone https://github.com/gnolang/getting-started.git


Suggestion: We also have the one line installer ⬇️
curl -fsSL https://raw.githubusercontent.com/gnolang/gno/master/misc/install.sh | sh

Proposing both would be nice

That one-liner is already here: it is exactly what make install runs, two steps below (step 2):

install: ## build the gno toolchain into $HOME/.gno/bin curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/gnolang/gno/master/misc/install.sh | sh -s -- --from-source

The line you commented on is step 1, git clone https://github.com/gnolang/getting-started.git, which clones this repo so there is a realm to build and edit. It is not the toolchain install; the two steps do different jobs.

One difference worth keeping: --from-source. Without it the installer takes its prebuilt-binary path, which looks for v* release tags and .tar.gz assets that gnolang/gno does not publish (it tags chain/*), so the bare curl … | sh fails today (gnolang/gno#6195, still open). The README says so in the paragraph right under step 2. Once #6195 is fixed the flag can go and the command becomes the short one you quoted.

So: Makefile as the single entry point, one command per step, and no second copy of the curl line to keep in sync.

Oh yes my bad you're right, thank you!

davd-gzl · 2026-09-17T14:57:49Z

-network:
+`hello_test.gno` shows the two tests every realm wants: one that exercises the
+state-changing function (note the `cur realm` parameter and the `cross(cur)`
+call — that's how Gno marks a "crossing" call into a realm), and one that calls


I think it's important to introduce the inter-realm spec (simplified) correctly if we do in that docs

Quick example: That's how Gno marks a "crossing" call into a realm. It changes the context from the realm it is running in into that realm context, mandatory for any function a user calls to change the realm's state (example: By using gnokey maketx)

Removed the hand-written explanation instead of correcting it. The sentence now links Realms and Interrealm, which say it properly and stay right when the semantics move. 6839827.

davd-gzl · 2026-09-17T15:25:53Z

@@ -0,0 +1,53 @@
+# AGENTS.md


We could enhance agents.md to index main documentations and document main error users could encounter if they modify that realm (as you did with gno is not go). We could modify the README in that direction (you can modify that realm, agent.md is made to help beginner // you can use an agent to create your first realm).

Close to other tools/skills we already made but here self contained, minimal and beginner oriented, which could work with "cheap model". No need to make something super fancy IMO, ~10/50 lines would do the work.

Example: missing realm param when calling with maketx call, render is not displaying (if putting incorrect names), else...

Took the indexing half, dropped the expansion. "Gno is not Go" is now six links (realms, interrealm, Go/Gno compatibility, stdlibs, testing, effective-gno) in place of five hand-written bullets: same length, nothing to keep in sync. The error catalogue you describe is worth having, but in the docs, not in a 52-line file that goes stale silently.

davd-gzl · 2026-09-17T15:28:27Z

+`hello_test.gno` shows the two tests every realm wants: one that exercises the
+state-changing function (note the `cur realm` parameter and the `cross(cur)`
+call — that's how Gno marks a "crossing" call into a realm), and one that calls
+`Render`, which is the realm's entire public surface.


entire public surface is not right words (there's also Get and Set serving as public function), Render should highlight its capability to displays md format into gnoweb

Correct, Get and Set are public too. The claim is gone from the README, and the test comment now just says gnoweb calls Render for every page view.

davd-gzl · 2026-09-17T15:37:29Z

We should hyperlink all this tools to their README

Went with one link rather than five: the install step points at Installation, which lists the tools and the other install methods.

davd-gzl · 2026-09-17T15:42:14Z

@@ -34,30 +34,53 @@

 4. Open your browser and visit http://localhost:8888


Say going to http://localhost:8888 on gnodev should redirect to that link if done correctly, with some troubleshoot if not

Linked it rather than written it: Local development with gnodev. Troubleshooting that drifts out of sync with gnodev is exactly what this pass is removing.

davd-gzl · 2026-09-17T15:43:45Z

-  `https://rpc.gno.land:443`) has been live since 12 September 2026. Real
-  GNOT, no faucet.
+`gnodev` runs a throwaway local chain. To put your realm on a real network,
+point `module` in `gnomod.toml` at a path you control — `gno.land/r/<your-address>/hello`


We should add little sentence about "how to create your key"
It is in upper part of the getting started https://docs.gno.land/builders/getting-started/#4-create-a-key

That page is already the target of the "Deploying it" link, and creating a key is step 4 on it, so there is nothing to add here.

It isn't, creating a key is the part 4 of the earlier part above the deployment section.
But, rethinking it, we could move that part into the deployment section. I will do a PR

davd-gzl

AI review, claude-opus-5, standard review, skills · Status: REQUEST CHANGES

davd-gzl · 2026-09-17T16:12:20Z

+- **Render must be deterministic.** Map iteration order is unspecified, so never
+  build output by ranging a map.


The premise beside this rule states the reverse: Gno ranges a map in insertion order on every run.

Suggested change

- **Render must be deterministic.** Map iteration order is unspecified, so never

build output by ranging a map.

- **Render must be deterministic.** Map iteration follows insertion order, which

is not a guarantee to build output on, so never build output by ranging a map.

Bullet removed. Insertion order is real but is not a guarantee to build output on, and neither version of that sentence belongs here: the section now links Effective Gno and the reference pages instead of restating them.

davd-gzl · 2026-09-17T16:12:20Z

+  first parameter `cur realm`, and callers use `cross(cur)`. See `Set` in
+  `hello.gno` and its call in `hello_test.gno`.


Nit: Set spells its crossing parameter _, not the cur realm this sentence promises, so only the test half of the pair shows one.

Right, and the bullet is gone. README links Realms and Interrealm rather than describing the signature.

davd-gzl · 2026-09-17T16:12:20Z

+  build output by ranging a map.
+- **The standard library is a subset.** `sort.Slice` does not exist, and `ufmt`
+  honours only some of `fmt`'s flags: `ufmt.Sprintf("%03d", 7)` returns `"7"`,
+  and `%-5s` comes back as `(unhandled verb: %-)`.


Nit: ufmt.Sprintf("%-5s", "ab") returns (unhandled verb: %-)5s, four characters longer than documented, and those four land in whatever the realm renders.

Suggested change

and `%-5s` comes back as `(unhandled verb: %-)`.

and `%-5s` comes back as `(unhandled verb: %-)5s`.

repro: the documented value is a prefix of the real one

# from a local clone of gnolang/getting-started: cat > zz_ufmt_test.gno <<'EOF' package hello import ( "testing" "gno.land/p/nt/ufmt/v0" ) func TestUfmtDash(t *testing.T) { t.Logf("%%-5s -> %q", ufmt.Sprintf("%-5s", "ab")) t.Logf("%%03d -> %q", ufmt.Sprintf("%03d", 7)) } EOF gno test -v . rm zz_ufmt_test.gno

The %-5s line carries four characters the documented value drops; the %03d line is there to show the neighbouring claim is exact.

# … === RUN TestUfmtDash %-5s -> "(unhandled verb: %-)5s" %03d -> "7" --- PASS: TestUfmtDash (0.00s) --- GAS: 1604805 # … ok . 0.53s

Your reading is right: the 5s survives the unhandled verb, and my measurement had a trailing | from the test string I used. The bullet is gone either way, replaced by a link to Standard libraries.

davd-gzl · 2026-09-17T16:12:20Z


-dev:
+dev: ## run a local chain + web UI on http://localhost:8888, reloading on save
 	gnodev .


Nit: dev calls gnodev by name while GNO ?= gno routes the other three, so a toolchain off PATH runs test, lint and fmt and fails the local chain.

Suggested change

gnodev .

GNO ?= gno

GNODEV ?= gnodev

Applied: GNODEV ?= gnodev, and dev calls $(GNODEV).

davd-gzl · 2026-09-17T16:12:20Z

+`make test lint` is the bar for any change. CI runs exactly those two targets
+against a gno built from `gnolang/gno` master, so a green local run means a
+green CI.


Suggestion: CI builds its gno from master at job time while GNO ?= gno takes whatever the contributor installed last, so a green local run promises no green CI.

Suggested change

`make test lint` is the bar for any change. CI runs exactly those two targets

against a gno built from `gnolang/gno` master, so a green local run means a

green CI.

`make test lint` is the bar for any change. CI runs exactly those two targets

against a gno built from `gnolang/gno` master, so a green run on a freshly

installed toolchain means a green CI. Re-run `make install` when CI disagrees.

davd-gzl · 2026-09-17T16:12:20Z

+`gnodev` runs a throwaway local chain. To put your realm on a real network,
+point `module` in `gnomod.toml` at a path you control — `gno.land/r/<your-address>/hello`
+always works and needs no registration — then follow


Related suggestion: Render hardcodes /r/example/hello, so a reader who re-points module ships a page whose one button calls a realm they do not own. Build the path from CurrentRealm().PkgPath() instead.

Fixed. Render no longer builds an absolute link. The page now says to add $help to its own URL, which works whatever module points at, and drops the hardcoded path with it.

davd-gzl · 2026-09-17T19:57:39Z

-network:
+Why `Set` takes a `realm` parameter and the test calls `cross(...)`:
+[Realms](https://docs.gno.land/resources/realms) and
+[Interrealm](https://docs.gno.land/resources/gno-interrealm).


https://docs.gno.land/resources/gno-interrealm-v2

davd-gzl · 2026-09-17T20:01:18Z

+do not guess:
+
+- [Realms](https://docs.gno.land/resources/realms): `Render` and realm state
+- [Interrealm](https://docs.gno.land/resources/gno-interrealm): crossing


https://docs.gno.land/resources/gno-interrealm-v2/

moul added 5 commits September 17, 2026 14:09

feat: make help, lint, fmt and deploy targets; CI runs the same targets

8749bf8

test: cover Render, the realm's only public surface

0c21452

feat: AGENTS.md for coding agents, and .gno syntax highlighting

3e6efaa

docs: how to test, how to deploy, and where to go next

7b26216

Delete .gitattributes

2369645

moul commented Sep 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

docs: link docs.gno.land for deploying, drop the deploy target and re…

375b021

…po-template link

moul changed the title ~~feat: make help, lint/fmt/deploy targets, a Render test, and AGENTS.md~~ feat: make help, lint/fmt targets, a Render test, and AGENTS.md Sep 17, 2026

moul added 2 commits September 17, 2026 14:24

Apply suggestion from @moul

94f6b18

docs: link gnopls and gno-mcp, restore the truncated ufmt line

dda245d

moul requested review from alexiscolin and davd-gzl September 17, 2026 12:53

davd-gzl suggested changes Sep 17, 2026

View reviewed changes

davd-gzl reviewed Sep 17, 2026

View reviewed changes

moul added 2 commits September 17, 2026 18:38

docs: link the official docs instead of restating them

694afe5

docs: drop em dashes

6839827

davd-gzl approved these changes Sep 17, 2026

View reviewed changes


		1. Clone this repository:

		git clone https://github.com/gnolang/getting-started.git

		@@ -34,30 +34,53 @@

		4. Open your browser and visit http://localhost:8888

		- Render must be deterministic. Map iteration order is unspecified, so never
		build output by ranging a map.

		first parameter `cur realm`, and callers use `cross(cur)`. See `Set` in
		`hello.gno` and its call in `hello_test.gno`.

	and `%-5s` comes back as `(unhandled verb: %-)`.
	and `%-5s` comes back as `(unhandled verb: %-)5s`.

Conversation

moul commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

davd-gzl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

moul Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davd-gzl Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davd-gzl Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davd-gzl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

moul commented Sep 17, 2026 •

edited

Loading

davd-gzl left a comment •

edited

Loading

moul Sep 17, 2026 •

edited

Loading

davd-gzl Sep 17, 2026 •

edited

Loading

davd-gzl Sep 17, 2026 •

edited

Loading

davd-gzl left a comment •

edited

Loading