docs: public-surface audit — README quick start, badges, AGENTS.md

[weboko]

Description

• README: add badges (crates.io / CI / license / MSRV), tighten tagline, add "What you get" bullets, promote 5-line Quick start to the top (cargo install logos-scaffold → lgs new → lgs run), add an Anchor / Cargo Stylus analogue paragraph for positioning, expand Documentation links (Contributing, Security, Dogfooding).
• README: drop em-dash density in Command Semantics from 11 → 3 by splitting dense clauses into separate sentences. No content lost.
• Cargo.toml: add keywords and categories so the crates.io listing and GitHub About panel have terms to surface.
• AGENTS.md (new): point at skills/*/SKILL.md, build/test commands, where things live, validation rules per CONTRIBUTING.md / DOGFOODING.md.

[weboko]

I need to re-review this PR before opening for the team

[weboko]

Review — public-surface audit (#181)

Reviewed the diff and validated the new Quick start hands-on on a clean Ubuntu 24.04 container (Rust 1.94.1, Nix 2.35.1, risc0 r0vm 3.0.5). Picking this one up because it is the only open PR with no review on it yet.

The framing is right — badges, a top-of-README quick start, an Anchor/Cargo Stylus positioning line and an AGENTS.md are all things this repo is missing. But the Quick start as written does not work against the crate it tells people to install, so it can't ship in this state.

Blocker — the Quick start fails at line 2

I ran exactly what the README now tells a new user to run:

$ cargo install logos-scaffold --root /tmp/lgs-published --locked
   Installed package `logos-scaffold v0.1.1` (executable `logos-scaffold`)

$ ls /tmp/lgs-published/bin/
logos-scaffold                      # <- no `lgs`

$ /tmp/lgs-published/bin/logos-scaffold --version
logos-scaffold 0.1.0                # <- cargo installed v0.1.1

$ /tmp/lgs-published/bin/logos-scaffold run --help
error: unrecognized subcommand 'run'

Published 0.1.1 (crates.io, 2026-04-14) exposes only create/new/setup/build/deploy/localnet/wallet/doctor/report. Three problems follow:

1. lgs is not installed. The lgs [[bin]] landed in 7dec5a9 (2026-05-13), a month after 0.1.1 was published. So lgs new my-app, lgs setup and lgs run are all command not found. Only the first of the five Quick start lines succeeds.

2. run does not exist in the published crate. So lgs run # build → localnet → deploy — the payoff line of the whole Quick start — cannot work, and neither can the lgs run, lgs build idl, lgs build client bullets in What you get.

3. The new sentence in Install from source states this explicitly and incorrectly:

   Both this and the cargo install logos-scaffold line in the Quick start install two binaries on your PATH: logos-scaffold and the shorter alias lgs.

   That is true for cargo install --path ., false for cargo install logos-scaffold.

Two ways out, either is fine: cut a release that actually contains lgs + run before merging this, or point the Quick start at cargo install --git https://github.com/logos-co/scaffold until such a release exists. What we can't do is ship a top-of-README quick start that 404s on its own second line — that is the single most-read block in the repo and the first thing a new user copies.

Worth deciding separately what to do about the installed 0.1.1 binary self-reporting 0.1.0.

Should fix before merge

4. Dead badge anchor. [![License](…)](#license) points at #license, but the README has no License heading (Documentation, Using scaffold as a Rust library, Platform, Scope, Prerequisites, Install, DOGFOODING, CLI, Command Semantics, First Success Path, LEZ Framework, Troubleshooting, Example Runs). Link it to LICENSE-MIT / LICENSE-APACHE, or add the section.

5. Stale prerequisite, promoted to the top of the file. The Quick start says:

   The first lgs setup needs Docker or Podman and a logos-blockchain-circuits release on disk.

   Since feat(scaffold): make circuits a project-level dependency #221 made circuits a project-level dependency this is no longer how it works. A fresh lgs new writes [circuits] version = "0.4.1" into scaffold.toml, and setup materialises the release itself. I confirmed this today — a fresh project pulled circuits into .scaffold/circuits with no LOGOS_BLOCKCHAIN_CIRCUITS and nothing in ~/.logos-blockchain-circuits/. (The existing ## Prerequisites section has the same drift; this PR is a good place to fix both, since it's now the text that greets everyone.)

6. Cargo.toml metadata is half-audited. The PR adds keywords/categories for crates.io discoverability but leaves the two fields that actually render as the listing headline:

   • description = "Rust CLI for bootstrapping LSSA program_deployment projects in standalone mode" — LSSA is the pre-LEZ name, and this PR's own README change is precisely a rename to LEZ.
   • repository = "https://github.com/logos-co/logos-scaffold" — 301s to logos-co/scaffold; worth pinning to the canonical URL while we're here.

Nits

7. Branch is ~2 months old and mergeable_state: dirty. Command Semantics has moved on master since, so rebase before another read.
8. lgs new already writes an AGENTS.md into generated projects. With a second one at the repo root there are now two files with the same name and different contracts. One line at the top of the root file ("this governs the scaffold repo itself, not projects created by lgs new") would stop an agent working in a generated project from loading the wrong contract.
9. The AGENTS.md validation table stops at D1–D5 / L1–L4. The runbook now also has D6, D7, the E/B/A/T series. At minimum add run / post-deploy-hook changes → D7, since run is the command this PR is promoting hardest.

Verified clean

Every link in AGENTS.md resolves: all four skills/*/SKILL.md exist, CONTRIBUTING.md#rate-limit exists, README.md#scope exists. The CI badge target .github/workflows/ci.yml exists and the workflow is active. The MSRV badge matches rust-version = "1.81". The em-dash de-densification in Command Semantics reads well and I could not find any content dropped in it.

Not approving — items 1–3 need a resolution first. Everything else is small.

---

Generated by Claude Code

[weboko]

Status update — the Quick start blocker is gone: 0.3.0 was published to crates.io yesterday

No new commits here since 24261e4, so this is not a re-review of the diff. I'm posting because the thing that blocked it was never in the diff — it was the state of the published crate — and that changed yesterday, 2026-08-18T23:22Z, when #251/#252 landed the version bump and publish-CI fix:

$ curl -s https://crates.io/api/v1/crates/logos-scaffold | jq -r '.crate.max_version'
0.3.0
   0.3.0 | 2026-08-18T23:22:23Z
   0.1.1 | 2026-04-14T07:17:24Z     <- what I tested against on 2026-07-28

I re-ran the exact Quick start this PR adds, against the published crate on a clean prefix. All three blocker points from my 2026-07-28 review are resolved:

1. lgs is now installed. This was the core failure — the lgs [[bin]] landed in 7dec5a9, a month after 0.1.1 was cut, so four of the five Quick start lines were command not found.

$ cargo install logos-scaffold --root /tmp/lgs-published --locked
   Installed package `logos-scaffold v0.3.0` (executables `lgs`, `logos-scaffold`)

$ ls /tmp/lgs-published/bin/
lgs  logos-scaffold

$ lgs --version
logos-scaffold 0.3.0

2. run exists in the published crate, with the same about line as master:

$ lgs run --help
Build, start localnet, top up wallet, deploy, and run post-deploy hooks (topup/deploy skippable)

lgs build idl ("Build IDL files from the current project") and lgs build client ("Build client code from IDL files") are there too, so the What you get bullets that referenced them are now accurate as written.

3. The Install-from-source sentence is now correct. "install two binaries on your PATH: logos-scaffold and the shorter alias lgs" is exactly what cargo install reports.

Quick start line 2 also runs clean end to end with the published binary:

$ cd /root/qs && lgs new my-app
Created logos-scaffold project from template …/examples/program_deployment at /root/qs/my-app
Pinned lez: cf3639d8252040d13b3d4e933feb19b42c76e14a
Template variant: default
AI skills installed under .claude/skills/, .cursor/rules/, and AGENTS.md.
   exit 0

Worth noting the published 0.3.0 pins the same LEZ commit cf3639d8 as master, so a reader following the Quick start lands on the same toolchain the repo tests against — which is what makes the published-crate path trustworthy to document at all. The MSRV badge (1.81) also still matches Cargo.toml.

What's still open

Only the mechanical part: this branch is draft and no longer merges — mergeable=false, mergeable_state=dirty against 834b6b0, 3 files. The README has moved a lot since May (#219's library section, #224, the run about line gaining (topup/deploy skippable)), so the rebase needs the Quick start and What you get re-checked against current master rather than replayed.

Two things I'd fold in while rebasing, both verified on 834b6b0:

• The overview should mention test-node and the logos_scaffold::api library surface — both landed in #219, after this branch was cut, and both belong in a "public surface audit".
• ## Prerequisites still says a logos-blockchain-circuits release can be placed at ~/.logos-blockchain-circuits/. src/circuits.rs:64-65 deliberately does not consult that path, and new projects need no manual circuits step at all — I raised this on #226 with a suggested replacement bullet, but it belongs to whichever README PR lands first.

Since the blocker that kept this in draft is cleared, this is now just a rebase away from being reviewable by the team.

---

Generated by Claude Code

[weboko]

updated version is in #253