docs: rebuild the public surface around install and first run (#253)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Something in the CLI does not work as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, run `lgs doctor`. It catches most environment problems
+        on its own and will tell you what is missing.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you ran, and what you got instead of what you expected.
+      placeholder: |
+        I ran `lgs run` in a fresh lez-framework project.
+        Step 3 failed with ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The shortest sequence of commands that shows the problem.
+      render: shell
+      placeholder: |
+        lgs new my-app --template lez-framework
+        cd my-app
+        lgs run
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Scaffold version
+      description: Output of `lgs --version`.
+      placeholder: logos-scaffold 0.3.0
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      description: OS and architecture. The CLI is Unix-only.
+      placeholder: macOS 15.3 arm64 / Ubuntu 24.04 x86_64
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics bundle
+      description: |
+        Run `lgs report` and attach the generated `.tar.gz`. It collects logs
+        and config through an allowlist with redaction, and reports anything it
+        skipped. Paste `lgs doctor --json` output here if you cannot attach the
+        bundle.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: project
+    attributes:
+      label: Project context
+      description: |
+        Which template, and whether you use a `[run]` profile, `basecamp`, or
+        `test-node`. Paste `scaffold.toml` if you can share it.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/logos-co/scaffold/blob/master/SECURITY.md
+    about: Read the security model before reporting anything involving wallets or keys.
+  - name: Command reference
+    url: https://github.com/logos-co/scaffold/blob/master/docs/commands.md
+    about: Full CLI surface and the exact semantics of each command.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,49 @@
+name: Feature request
+description: Propose a change to the CLI or its templates
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Read [CONTRIBUTING.md](https://github.com/logos-co/scaffold/blob/master/CONTRIBUTING.md) first. This
+        project prioritizes friction hit by people building real projects on
+        the Logos stack. Requests without that grounding are triaged last.
+
+  - type: textarea
+    id: friction
+    attributes:
+      label: What friction did you hit
+      description: |
+        Describe the problem in terms of what you were trying to build, not the
+        solution you have in mind.
+      placeholder: |
+        My project funds its own accounts, so scaffold's topup step ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: What you do today
+      description: The workaround you currently use, or why there isn't one.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: What you would like the CLI to do. Include the command shape if you have one in mind.
+    validations:
+      required: false
+
+  - type: input
+    id: project-link
+    attributes:
+      label: Project link
+      description: |
+        A link to the project that hit this, or to an issue or discussion showing
+        someone else did. Leave blank if neither exists.
+      placeholder: https://github.com/...
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -39,5 +39,5 @@ Generic "this would be nice" does not count.
 
 - [ ] CI is green
 - [ ] Relevant DOGFOODING scenarios rerun (listed above)
-- [ ] Docs updated (`README.md`, `DOGFOODING.md`) if user-facing behavior changed
+- [ ] Docs updated (`README.md`, `DOGFOODING.md`, plus `docs/commands.md` for a command or flag change and `docs/configuration.md` for `[run]` config changes) if user-facing behavior changed
 - [ ] I have read [CONTRIBUTING.md](/CONTRIBUTING.md) and this PR fits within the weekly contribution cap

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+Context for AI coding agents working in this repository.
+
+## What this repo is
+
+`logos-scaffold` is a Rust CLI that builds, runs, and deploys Logos programs
+against a local execution zone. It ships two binaries from one crate:
+`logos-scaffold` and the alias `lgs`. They are functionally identical.
+
+The crate also exposes a typed Rust API under `logos_scaffold::api`, so the CLI
+and the library are two front ends over the same code. A change to command
+behaviour usually needs a matching change to the API surface.
+
+## Driving the CLI
+
+If your task is to *use* scaffold rather than change it, read the skills in
+`skills/` instead of this file. They are the maintained instructions:
+
+| Skill | Use it for |
+|---|---|
+| `skills/lgs-cli` | Entry point. Driving the CLI, diagnosing errors, adopting scaffold in an existing project. |
+| `skills/lez-template` | Working inside a default-template project. |
+| `skills/lez-framework-template` | Working inside a `--template lez-framework` project. |
+| `skills/basecamp` | Any `lgs basecamp` subcommand, or a project that builds `.lgx` modules. |
+
+`skills/lgs-cli` routes into the other three once it knows the project type.
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `src/commands/` | One module per CLI command. Start here for behaviour changes. |
+| `src/api/` | Public Rust API. Keep in sync with command behaviour. |
+| `src/cli.rs` | clap definitions. The source of truth for flags. |
+| `templates/` | Project templates: `default` and `lez-framework`. |
+| `skills/` | Agent skills, shipped into scaffolded projects. |
+| `tests/` | Integration tests driven through `assert_cmd`. |
+| `docs/` | User documentation. |
+
+## Before you change anything
+
+Read `CONTRIBUTING.md` first. This project has an explicit triage bar: changes
+should trace to a real project hitting real friction, or to demonstrated user
+demand. Speculative refactors are likely to be closed.
+
+## Checks
+
+CI runs exactly these three, in this order:
+
+```bash
+cargo fmt --check
+cargo check
+cargo test
+```
+
+`.github/workflows/ci.yml` is authoritative. Run all three before opening a PR.
+
+## Documentation rules
+
+- `src/cli.rs` and `--help` are the source of truth for flags. `docs/commands.md`
+  documents them and must be updated in the same change.
+- `README.md` is the front door. Keep it short and keep install and first-run
+  above the fold. Reference material belongs in `docs/`.
+- `DOGFOODING.md` is the canonical runbook. Update it whenever first-class
+  commands, templates, or supported workflows change.
+- `ADR.md` records architecture decisions and `FURPS.md` records requirements.
+  Add to them rather than rewriting history.
+
+## Constraints worth knowing
+
+- The CLI is Unix-only. Localnet and process detection shell out to `lsof`,
+  `ps`, and `kill`.
+- Dependencies (LEZ, spel, basecamp, lgpm) are pinned by commit in
+  `scaffold.toml` and resolved under a cache root at runtime. Do not hardcode
+  checkout paths.
+- Project-local binaries are never installed to PATH. Reach them through
+  `lgs wallet -- …` and `lgs spel -- …`.
+- Commands that produce machine-readable output take `--json`. Adding output to
+  a command means considering both paths.

CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples include using an official email address, posting via an official social
+media account, or acting as an appointed representative at an online or offline
+event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers through GitHub's
+[report abuse](https://github.com/contact/report-abuse) flow, or by contacting
+a maintainer directly.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. Violating
+these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. Violating these
+terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla].
+
+[homepage]: https://www.contributor-covenant.org
+[mozilla]: https://github.com/mozilla/diversity
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -9,6 +9,21 @@
 
 Generic cleanups, cosmetic refactors, and "this would be nice" PRs from contributors with no connection to either of the above are the lowest triage priority and are likely to be closed.
 
+## Project Documents
+
+| Document | What it holds |
+|---|---|
+| [AGENTS.md](./AGENTS.md) | Repo orientation for AI coding agents |
+| [FURPS.md](./FURPS.md) | Functional and non-functional requirements |
+| [ADR.md](./ADR.md) | Architecture decision records |
+| [DOGFOODING.md](./DOGFOODING.md) | Canonical validation runbook (`D1`-`L4`) |
+| [docs/commands.md](./docs/commands.md) | Full CLI surface and command semantics |
+| [docs/configuration.md](./docs/configuration.md) | `[run]` profiles, hooks, watch mode |
+| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | Community standards |
+
+Add to `FURPS.md` and `ADR.md` rather than rewriting them. They are a record,
+not a description of the current state.
+
 ## Before You Open a PR
 
 You should have:
@@ -26,7 +41,7 @@ Plus:
 - **Scoped.** One concern per PR. No drive-by refactors.
 - **Green CI.**
 - **Verified.** Applicable DOGFOODING scenarios rerun. See [DOGFOODING.md](./DOGFOODING.md) — "Minimum Rerun Guidance for Future Changes".
-- **Documented.** If the change affects user-facing behavior, update `README.md` and `DOGFOODING.md` in the same PR.
+- **Documented.** If the change affects user-facing behavior, update `README.md` and `DOGFOODING.md` in the same PR. If it changes a command or a flag, update [`docs/commands.md`](./docs/commands.md) too; if it changes `[run]` config, update [`docs/configuration.md`](./docs/configuration.md).
 
 ## LLM-Assisted PRs
 

Cargo.toml

@@ -1,11 +1,11 @@
 [package]
 name = "logos-scaffold"
 version = "0.3.0"
-description = "Rust CLI for bootstrapping LSSA program_deployment projects in standalone mode"
+description = "Command-line toolkit for building, running, and deploying Logos programs against a local execution zone"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
-repository = "https://github.com/logos-co/logos-scaffold"
+repository = "https://github.com/logos-co/scaffold"
 rust-version = "1.81"
 include = [
   "/src/**",

FURPS.md

@@ -96,7 +96,7 @@
 ### Supportability
 
 1. `[run]` round-trips cleanly through `parse_config` / `serialize_config`. Default values are omitted from the serialized output to keep diffs minimal.
-2. The hook env contract is documented in `README.md` and validated by unit and integration tests in `src/commands/run.rs::tests` and `tests/cli.rs`.
+2. The hook env contract is documented in `docs/configuration.md` and validated by unit and integration tests in `src/commands/run.rs::tests` and `tests/cli.rs`.
 3. Flag-conflict rejection messages list the conflicting flags and exit non-zero, matching clap's standard error format.
 
 ### + (Privacy, Anonymity, Censorship-Resistance)

docs/configuration.md

@@ -0,0 +1,159 @@
+# Configuring `lgs run`
+
+`lgs run` is the inner loop: it chains build (which chains setup), IDL build,
+localnet start, wallet topup, and deploy into one command. It works with no
+configuration at all. This page covers the `[run]` section of `scaffold.toml`
+for projects that need to change what the pipeline does.
+
+For the command surface itself, see [commands.md](./commands.md).
+
+To run one or more post-deploy hooks automatically (e.g. submit a transaction
+with [spel](https://github.com/logos-co/spel)), add a `[run]` section to
+`scaffold.toml`. `post_deploy` is a list of shell commands executed in order;
+the run aborts at the first non-zero exit:
+
+```toml
+[run]
+post_deploy = [
+  "lgs spel -- --idl $SCAFFOLD_IDL_DIR/counter.json -p $SCAFFOLD_GUEST_BIN init",
+  "lgs spel -- --idl $SCAFFOLD_IDL_DIR/counter.json -p $SCAFFOLD_GUEST_BIN increment --by 5",
+]
+```
+
+The `lgs spel --` passthrough invokes the project-vendored `spel` binary
+so hooks pick up the same pinned version `deploy` used.
+
+A single command may also be written as a plain string for brevity:
+`post_deploy = "echo done"`.
+
+Each hook runs via `sh -c` with cwd set to the project root and these
+environment variables pre-set:
+
+| Variable | Value |
+|---|---|
+| `SEQUENCER_URL` | `http://127.0.0.1:<port>` (from `scaffold.toml`) |
+| `NSSA_WALLET_HOME_DIR` | Absolute path to project wallet directory (name read by LEZ up to v0.1.2) |
+| `LEE_WALLET_HOME_DIR` | Same path under the name LEZ v0.2.0 reads. Both are always set, so a hook that execs the wallet binary works on either pin |
+| `SCAFFOLD_PROJECT_ROOT` | Absolute path to project root |
+| `SCAFFOLD_IDL_DIR` | Absolute path to IDL output directory |
+| `SCAFFOLD_TOPUP_SKIPPED` | `1` when step 4 was skipped (`topup = false`), `0` when scaffold topped up the wallet. Always set |
+| `SCAFFOLD_DEPLOY_SKIPPED` | `1` when step 5 deployed nothing — either `deploy = false`, or the deploy cache found guest binaries, IDL, config and sequencer unchanged — and `0` when it deployed. Always set |
+| `SCAFFOLD_PROGRAM_ID` | risc0 image ID (hex) of the deployed program. Set only when the project has exactly one deployable program; unset if `spel program-id` cannot extract the ID |
+| `SCAFFOLD_GUEST_BIN` | Absolute path to the guest `.bin`. Set only when the project has exactly one deployable program |
+
+`SCAFFOLD_TOPUP_SKIPPED` and `SCAFFOLD_DEPLOY_SKIPPED` describe the run as a
+whole, so they are set on every hook invocation — including for projects with
+no deployable programs, where `SCAFFOLD_PROGRAM_ID` and `SCAFFOLD_GUEST_BIN`
+are absent. Hooks should branch on their `1`/`0` value, not on whether they
+exist.
+
+`SCAFFOLD_PROGRAM_ID` and `SCAFFOLD_GUEST_BIN` are unset for
+multi-program projects so hooks fail loudly rather than silently
+picking up the wrong program.
+
+## Self-deploying projects (`deploy = false`)
+
+`run` deploys programs it finds under `methods/guest/src/bin`. A project
+that owns deployment itself — it deploys from a `post_deploy` hook, or keeps
+its guest program outside that default directory — can set `deploy = false`
+to skip scaffold's deploy step (step 5). The pipeline then runs
+build → IDL → localnet → topup → `post_deploy`, without requiring the default
+program directory to exist. It works inline under `[run]` or per profile:
+
+```toml
+[run.profiles.demo]
+deploy = false
+post_deploy = ["scripts/deploy-and-demo.sh"]
+```
+
+It is equally valid inline under `[run]` (applies to the default, profile-less run):
+
+```toml
+[run]
+deploy = false
+post_deploy = ["scripts/deploy-and-demo.sh"]
+```
+
+`deploy` defaults to `true`; omit it for the normal deploy loop.
+
+A named profile is used **as-is**: selecting one (via `--profile NAME` or
+`[run].default_profile`) shadows the inline `[run]` values entirely rather
+than inheriting them. So `deploy = false` under `[run]` combined with
+`--profile demo` — where `demo` omits the key — deploys, because `demo`
+supplies its own default of `true`. This applies to every profile key
+(`reset`, `deploy`, `topup`, `post_deploy`): whatever a profile does not
+state, it defaults, it does not inherit. Set the key in each profile that
+needs it.
+
+## Self-funding projects (`topup = false`)
+
+`run` tops up the project's default wallet before deploying (step 4). A
+project that funds its own accounts — e.g. its demo binary claims from the
+faucet at runtime, or a `post_deploy` hook handles funding — can set
+`topup = false` to skip that step and keep funding in one place instead of
+splitting it between scaffold and the project. The pipeline then runs
+build → IDL → localnet → deploy → `post_deploy`. It works inline under
+`[run]` or per profile, and combines with `deploy = false`:
+
+```toml
+[run.profiles.demo]
+topup = false
+post_deploy = ["cargo run --bin demo"]
+```
+
+Hooks see `SCAFFOLD_TOPUP_SKIPPED=1` on such a run, so a funding hook can
+claim only when scaffold did not. The topup step itself needs a destination
+address, but on a pin whose wallet config ships preconfigured accounts one is
+already in place by step 4: step 1 of every `lgs run` chains `lgs setup`,
+which seeds `.scaffold/state/wallet.state` from the first preconfigured
+public account whenever that file is missing — and `--reset`, which wipes the
+wallet later, at step 3, re-seeds it before the run continues.
+
+Skipping topup does not move the funding requirement, only the responsibility
+for meeting it. With the default `deploy = true`, step 5 still runs against
+whatever the wallet holds — so if the deploy path needs funds, the project
+has to provide them *before* deploy, not from a `post_deploy` hook that runs
+after it. A project that funds from a hook generally wants `deploy = false`
+too, and to deploy from that same hook after funding.
+
+`topup` defaults to `true`; omit it for the normal topup-then-deploy loop.
+
+## One-off override / skip
+
+To run a different hook without editing `scaffold.toml`:
+
+```bash
+lgs run --post-deploy "scripts/smoke.sh"
+lgs run --post-deploy "step-a" --post-deploy "step-b"   # repeatable
+lgs run --no-post-deploy                                 # skip all hooks
+```
+
+`--post-deploy` and `--no-post-deploy` conflict with each other and
+both override whatever `[run].post_deploy` defines.
+
+## Watch mode
+
+`lgs run --watch` re-runs the pipeline on each filesystem change (localnet
+is reused; reset is skipped on re-runs). Scope what counts as a change with
+`[run.watch]` and tune the coalescing window:
+
+```toml
+[run.watch]
+include = ["programs/**/guest/**", "contracts/**/*.sol"]
+exclude = ["**/*.md", "Cargo.lock"]
+debounce_ms = 1500
+```
+
+A changed path triggers a re-run **iff** it matches at least one `include`
+glob (or `include` is unset, meaning "any path") **and** matches zero
+`exclude` globs — `exclude` always wins. Globs are project-relative,
+gitignore-style: `**` spans path segments, `*`/`?` match within a segment,
+and a slash-less pattern (`Cargo.lock`) matches at any depth. `.scaffold`,
+`target`, `.git`, and the IDL output dir are always ignored regardless of
+these filters. Override the debounce per invocation with
+`lgs run --watch --watch-debounce-ms 1500` (CLI wins over
+`[run.watch].debounce_ms`, which wins over the 500ms default).
+
+To check what a configured run actually did, `lgs localnet status` reports the
+sequencer and `lgs doctor` reports the project.
+

docs/social-preview-brief.md

@@ -0,0 +1,56 @@
+# Social preview image brief
+
+The repo currently has no uploaded social preview, so GitHub generates a
+fallback from the avatar and repo name. That fallback is what renders in every
+Slack, Discord, X, and LinkedIn unfurl of a scaffold link.
+
+## Specification
+
+| Property | Value |
+|---|---|
+| Dimensions | 1280 × 640 px (GitHub's 2:1 ratio) |
+| Format | PNG |
+| File size | Under 1 MB |
+| Upload | Settings → General → Social preview → Edit |
+| Safe area | Keep all text inside a 1100 × 500 centered box. Clients crop the edges. |
+
+## Content
+
+Three elements, nothing else.
+
+1. **Wordmark**: `logos-scaffold`. Monospace, heavy weight, largest element on
+   the canvas.
+2. **Tagline**: `Build, run, and deploy Logos programs against a local
+   execution zone.` One line if it fits at a legible size, two if not. This is
+   the README tagline, trimmed. Keep them in sync.
+3. **Proof**: a terminal fragment showing the inner loop. Four lines is enough:
+
+   ```
+   $ lgs run
+   [3/5] Ensuring localnet...
+   [5/5] Deploying programs...
+   Sequencer: http://127.0.0.1:3040
+   ```
+
+   Use real CLI output. Do not invent step labels; they come from
+   `src/commands/run.rs`.
+
+## Design notes
+
+- Unfurls render small. Test at 25% zoom: if the tagline is unreadable there,
+  the type is too small. Wordmark should survive down to a 320 px wide preview.
+- Dark background, light text. Most unfurl surfaces are dark, and a light card
+  glares.
+- One accent color, used once. Suggested: the `Sequencer:` line or the
+  `[5/5]` step marker, so the eye lands on the payoff.
+- No stock imagery, no gradients behind text, no logo soup. The terminal
+  fragment is the visual.
+- Leave the bottom-right corner clear. Some clients overlay a domain label
+  there.
+
+## Do not include
+
+- Star counts, download numbers, or any metric. They date immediately and this
+  project's numbers are small enough that quoting them works against it.
+- "Powered by" badges or partner logos.
+- A version number. It forces a re-render on every release.