docs: rebuild the public surface around install and first run

[weboko]

Description

After so many iterations, especially using AI README.md file became one big pile of stuff.
I want to improve it, drop it into smaller files and make experience reading it pleasant.

User Story

A developer arriving at the repo could not get from landing to a running project. The README opened with links to FURPS.md and ADR.md, internal engineering documents. Install sat at line 55, behind a seven-item prerequisites wall, and read cargo install --path ., which assumes a clone the README never mentions. The first runnable command was at line 177 of 437. Measured against Foundry, Anchor, Stellar CLI, Hardhat, and dfx, tagline-to-install runs 12–26 lines; this repo was 51, and tagline-to-first-command was 174 against their 15–25.

Separately, the crates.io page carried a description saying "LSSA", a term with zero remaining occurrences in the README, and a repository URL (logos-co/logos-scaffold) that returns 403.

Change Summary

Restructures the README around install and first run, moves reference material into docs/, and fixes the two broken Cargo.toml metadata fields. README goes 437 → 280 lines. Nothing is deleted: the command dump and Command Semantics move to docs/commands.md, run configuration to docs/configuration.md, and FURPS/ADR/DOGFOODING pointers to a Project Documents table in CONTRIBUTING.md. Adds AGENTS.md, CODE_OF_CONDUCT.md, issue templates, and a social preview brief.

It also carries a one-line cargo fmt fix to src/process.rs. That is not documentation, but cargo fmt --check is CI's first step and has been failing on master since the setsid daemonize change, so this branch inherited a red run. Happy to split it out if you would rather fix master directly.

Verification

• cargo fmt --check, cargo check, cargo test pass locally on the merged branch (769 tests).
• Every command signature in docs/commands.md re-checked against --help from a build of this branch. That turned up the missing --json on localnet logs / wallet list / wallet topup, the missing --timeout-sec on test-node start / run, and four basecamp subcommands the page did not list at all (build, run, paths, docs).
• The README circuits prerequisite was wrong: src/circuits.rs never reads ~/.logos-blockchain-circuits/ (its module docs explain why), it downloads the pinned release into .scaffold/circuits itself. Corrected to match templates/default/README.md.

Rebased on master (26 Aug)

Merged master. The README conflicted wholesale, since #256 edited four basecamp bullets in the old Command Semantics section that this branch had already moved to docs/commands.md. Resolution keeps the restructured README and ports those bullets (setup, modules, launch, doctor) to where the text now lives. #258 landed the same cargo fmt fix this branch carried, so src/process.rs merged clean.

Two pointers master had moved past also got carried over: the setsid daemonization sentence #34 added to the localnet start bullet, and FURPS Supportability #2, which pointed at README.md for the hook env contract that now lives in docs/configuration.md.

Re-verified the whole basecamp command surface against --help after the merge; #256 changed behaviour, not flags, so the signatures still hold.

Left for maintainers

• The repo About panel has no topics and its description predates this tagline; the social preview is still GitHub's fallback. Both are repo settings, not files, so they cannot ship in a PR. docs/social-preview-brief.md has the spec for the image.
• CODE_OF_CONDUCT.md now points reports at GitHub's report-abuse flow. Swap in a dedicated address if one exists.

[Copilot]

Pull request overview

Restructures the repository’s public documentation so a new developer can get from landing → install → first successful run quickly, while moving deep reference material into docs/ and adding contributor-facing repo hygiene files (agents guidance, CoC, issue templates).

Changes:

• Rebuilds README.md around “Quick start”, install, and troubleshooting; moves detailed command/config reference into docs/.
• Adds new documentation assets (docs/commands.md, docs/configuration.md, docs/social-preview-brief.md) plus a VHS recording script (demo.tape).
• Fixes crates.io metadata in Cargo.toml (description + repository URL) and adds repo community/maintenance files (CoC, issue templates, AGENTS guidance).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Reorganized entry-point docs to surface install + first run and link out to reference docs.
docs/social-preview-brief.md	Brief for creating a GitHub social preview image aligned with README messaging.
docs/configuration.md	Extracted detailed [run] / lgs run configuration reference out of the README.
docs/commands.md	Extracted full CLI command/flag reference and semantics out of the README.
demo.tape	Adds a reproducible “hero” terminal recording script for README media.
CONTRIBUTING.md	Adds a “Project Documents” index and clarifies doc-update expectations for CLI/config changes.
CODE_OF_CONDUCT.md	Adds a Contributor Covenant Code of Conduct for community standards.
Cargo.toml	Updates crate description and repository URL metadata.
AGENTS.md	Adds repo orientation and workflow guidance for AI coding agents and contributors.
.github/ISSUE_TEMPLATE/feature_request.yml	Adds a structured feature request issue form.
.github/ISSUE_TEMPLATE/config.yml	Adds issue template config + contact links (security, command reference).
.github/ISSUE_TEMPLATE/bug_report.yml	Adds a structured bug report issue form emphasizing diagnostics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/ISSUE_TEMPLATE/feature_request.yml:8

• The issue form markdown uses a relative link (../blob/master/...) that won't resolve correctly from rendered GitHub issue forms. Use an absolute URL like the other contact links in .github/ISSUE_TEMPLATE/config.yml so users can open CONTRIBUTING reliably.

        Read [CONTRIBUTING.md](../blob/master/CONTRIBUTING.md) first. This

README.md:67

• This section says "every command" but includes curl specifically for "first setup", which is not required for every command. Rewording avoids confusing readers about what they must install up-front.

You need these for every command:

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

README.md:79

• The prerequisites section suggests users can satisfy the circuits dependency by placing a release under ~/.logos-blockchain-circuits/, but the code explicitly avoids that fallback and instead downloads/install circuits into the project’s [circuits].install_dir (default .scaffold/circuits) unless LOGOS_BLOCKCHAIN_CIRCUITS is set. This guidance is likely to mislead users on a fresh machine.

- A `logos-blockchain-circuits` release on disk, required by the LEZ standalone
  build chain that `setup` invokes. Set `LOGOS_BLOCKCHAIN_CIRCUITS=<path>` or
  place the release at `~/.logos-blockchain-circuits/`.

docs/commands.md:42

• localnet logs supports --json output (see LocalnetLogsArgs in src/cli.rs), but the command signature here omits it, which makes this reference incomplete/inaccurate for tooling usage.

logos-scaffold localnet logs [--tail N]

docs/commands.md:65

• Wallet subcommands also support --json (both wallet list and wallet topup), but the signatures here omit it. Since this file is intended as a flag reference, these options should be listed.

logos-scaffold wallet list [--long]
logos-scaffold wallet topup [<address> | --address <address-ref>] [--dry-run]

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[weboko]

Review + verification of the documented surface

The restructure achieves what it set out to. Landing on tagline → quick start → what you get → prerequisites → install reads the way the comparable tools do, and moving the command dump into docs/commands.md without deleting anything is the right call.

I checked the documentation claims mechanically rather than by eye, since that is where docs PRs usually rot.

Command surface — clean. I extracted every lgs/logos-scaffold invocation from docs/commands.md and resolved each against --help on a build of this branch: 31/31 commands resolve. I then extracted every documented command/flag pair and checked each flag appears in that subcommand's help: 31 pairs, zero mismatches. No documented flag is missing from the CLI. Your claim about re-checking each signature against --help holds up.

Quick start runs as written. lgs new my-app --template lez-framework succeeds against the pinned LEZ and produces the expected tree, and --template lez-framework is still a valid choice (available: default, lez-framework).

Cargo.toml metadata — both fixes are real. logos-co/scaffold returns 200; the old logos-co/logos-scaffold returns a 301 redirect (a 403 for the unauthenticated crates.io fetch is consistent with that). The description no longer says "LSSA", which had no remaining occurrences in the README.

Prerequisites correction is right. src/circuits.rs does download the pinned release into .scaffold/circuits itself; ~/.logos-blockchain-circuits/ appears only in the module docs as an env-var override, never as a read path. The corrected text matches the code and templates/default/README.md.

On the src/process.rs line — please keep it, and consider landing it first

You offered to split it out. I would keep it, and I would treat it as the most time-sensitive thing in this PR.

I confirmed independently that master is fmt-dirty and has been since bd2574d (#34, the setsid daemonize change): 834b6b0 was the last green master commit, bd2574d and 20b9d99 are both red, and validate runs cargo fmt --check as its first step. So this is not just "this branch inherited a red run" — every open PR is currently red for a reason unrelated to its own contents (#255 and #256 both, and #256 does not touch src/process.rs at all). I verified this branch is fmt-clean with the fix applied.

Either merging this PR or cherry-picking 41640dc1 straight onto master unblocks CI repo-wide. Given the rest of this PR is docs and will attract prose review, cherry-picking that one hunk to master now is probably the faster route to a green board — but either works, and the fix belongs somewhere regardless.

Small notes

• The Quick start's lgs run sample output is labelled as literal CLI output with <…> placeholders for user values, which is honest and worth keeping in that form.
• "The first run compiles the LEZ toolchain from source, so expect it to take a while" is a genuinely useful expectation-setter that the old README lacked.
• docs/social-preview-brief.md plus the "Left for maintainers" section is a good way to hand off the repo-settings work that cannot ship in a diff.

No blocking findings. The docs match the binary, which is the bar for this kind of change.

---

Generated by Claude Code

[weboko]

Review: docs restructure — verified end-to-end ✅

Set up a full toolchain (Nix+flakes, Rust, risc0 r0vm 3.0.5 + guest toolchain) and validated the PR's central claim by running the new README Quick start verbatim against a real sequencer:

lgs new my-app --template lez-framework
lgs run      # [1/5]..[5/5] → localnet ready (pid), program_id 90e8f478…, Sequencer: http://127.0.0.1:3040
lgs wallet -- check-health   # exit 0

The printed step labels and "Sequencer: http://127.0.0.1:3040" line match the README's console block exactly.

Docs accuracy checks (all pass):

• Every command signature in docs/commands.md re-verified against --help on a build of this branch — localnet logs --json, wallet list --json, wallet topup --json, test-node start --timeout-sec, run, deploy, localnet reset, the basecamp subcommands. All match.
• Relative links in README / docs / CONTRIBUTING resolve within the tree; AGENTS.md's "CI runs exactly these three" matches .github/workflows/ci.yml.
• The process.rs cargo fmt fix is legitimate: it's the sole thing making cargo fmt --check (CI's first step) red on master since #34, and it's a pure whitespace fix. Fine to carry here.

One cross-PR coordination note (non-blocking): docs/commands.md correctly says "init writes scaffold.toml (schema v0.2.0)" for this branch. #255 makes 0.3.0 current — whichever of these two lands second should update that line and the init/migration description to v0.3.0 so the docs and the code agree.

Reads clean and the DX is a real improvement. No blocking issues.

---

Generated by Claude Code

[weboko]

Re-review: docs restructure — README quick start verified verbatim against a real run

Environment: Nix 2.35.2, Rust 1.94.1, r0vm 3.0.5 + risc0 guest toolchains (rust r0.1.91.1, cpp 2024.01.05), real LEZ sequencer + wallet from cf3639d8, circuits v0.4.1. cargo test --lib on dc40fdb: 562 passed, 0 failed.

I ran the new Quick start block as written, on a clean project, and it does what it says:

lgs new my-app --template lez-framework
cd my-app
lgs run
lgs wallet -- check-health

• lgs run → [1/5] Building... [2/5] Building IDL... [3/5] Ensuring localnet... [4/5] Topping up wallet... [5/5] Deploying programs..., all five labels byte-identical to the console block in the README.
• localnet ready (sequencer pid=11438), real faucet claim executed, lez_counter deployed (program_id: 90e8f478d4dea5ac29c1b664da80294c0b1cecf4648f7c32528b0a6d27fe2be9), and the closing Sequencer: http://127.0.0.1:3040 line matches the block exactly.
• lgs wallet -- check-health → ✅All looks good!, exit 0.
• The prose claim "Every run after that reuses a running localnet and skips deploy when nothing changed" also holds — a second lgs run printed [5/5] Deploy skipped (guest binaries + IDL + config + sequencer unchanged; …).

Other accuracy checks, all pass:

• Every internal link in README resolves at this tree (11/11), as does every relative link in docs/commands.md, docs/configuration.md, and CONTRIBUTING.md (13/13) — including the deep link ./DOGFOODING.md#minimum-rerun-guidance-for-future-changes.
• All three issue templates parse as valid YAML.
• I cross-checked every logos-scaffold … invocation in docs/commands.md against the real CLI's --help output: 48/48 valid, subcommands included (build idl, localnet reset, test-node snapshot, basecamp build-portable, wallet default, …). No documented command or subcommand is missing from the binary, and no top-level command is missing from the doc. (My checker flagged logos-scaffold help — false positive; clap's built-in help works, it just isn't listed under Commands:.)
• cargo install logos-scaffold — the first line of the quick start — is real: the crate is published, max_stable_version 0.3.0, and it ships both lgs and logos-scaffold bin targets, so the lgs alias used throughout the new docs is available straight from that install.

Cargo metadata fixes are correct and overdue. The published 0.3.0 on crates.io still carries repository = "https://github.com/logos-co/logos-scaffold" (a stale path) and the old "Rust CLI for bootstrapping LSSA program_deployment projects in standalone mode" description. Both are fixed here, so the next publish corrects the crates.io landing page. Worth calling out because it is the one change in this PR with reach outside the repo.

The restructure itself reads well. Tagline → quick start → what you get → prerequisites → install is the right order, moving the exhaustive command list into docs/commands.md makes the README skimmable, and the src/process.rs hunk is a pure rustfmt fix over master's daemonize commit — no behaviour change.

---

Non-blocking nits

1. --template lez-framework in the quick start. This is the very first command a new user runs, and it hard-codes a template name that PR feat(template): rename lez-framework to spel; delegate scaffolding to spel init #199 proposes renaming to spel. Not this PR's problem, and feat(template): rename lez-framework to spel; delegate scaffolding to spel init #199 is nowhere near landing, but whoever merges second owns updating this block — worth a note so it doesn't silently rot into a deprecation warning on the headline example.

2. The "first run compiles the LEZ toolchain from source, so expect it to take a while" line undersells it. On my box that first run was several minutes of sequencer_service + wallet + guest compilation on a warm cache, and materially longer cold. A rough order of magnitude ("expect 10–20 minutes on a cold cache") would set expectations better than "a while" — the current wording risks a user assuming it hung. Entirely optional.

---

Verdict: approve. Everything the docs claim, I checked, and it held — including the one claim that actually matters (the quick start runs verbatim end-to-end on a fresh machine). This is the lowest-risk PR of the four open ones: docs plus a formatting fix plus two Cargo metadata corrections, no behavioural change, tests green.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs/commands.md:43

• The localnet reset usage line implies --yes and --dry-run are mutually exclusive ((--yes | --dry-run)), but the CLI currently allows both flags (there is no clap conflicts_with between them). Since this doc claims signatures were verified against --help, the usage line should match what --help would show.

logos-scaffold localnet reset (--yes | --dry-run) [--reset-wallet] [--verify-timeout-sec N]