lfdt-lineth/lineth-monorepo/lineth-quickstart

Lineth Stack quickstart — agent skill

This skill helps you operate the Lineth Stack quickstart: a Docker-Compose dev/demo stack that boots a local Linea/Lineth L2 settled by either Sepolia (default, real public L1) or a self-contained local Besu+Teku L1. It is a dev/demo tool, not a production deployment.

The skill does not restate the boot procedure — that has one source of truth in the package, and duplicating it here would let the two drift apart. Your job is to route to that source, then layer on the failure triage and change/commit rules the skill bundles.

Start here

Run everything from docs/getting-started/lineth-stack/ (find it with git rev-parse --show-toplevel then cd in). Then read these two files before acting — they are the procedure, and if anything here ever disagrees with them, they win:

• AGENTS.md — the canonical operating runbook: preflight, L1-mode choice, the boot commands, the

Sepolia funding stop, success signals, reset, and guardrails. Follow it step by step.

• README.md — the operator guide it draws on: endpoints, gas caps, prover modes, full

troubleshooting.

Don't work from memory or from this file's summary — the stack is nonce/order-sensitive and artifact-driven, so a 60-second read of the current AGENTS.md prevents a failed boot.

Two things agents most often get wrong

These are the classic false steps; AGENTS.md has the detail, but keep them front of mind:

• The Sepolia first-boot "exit" is expected, not an error. First Sepolia boot generates the

deployer keystore, prints the address + funding amount, and stops before any container starts. You cannot fund it — surface the address to the human, then rerun the same command. For unattended runs, choose --l1-mode local instead, which needs no funding.

• Success means finality, not a blob. Report success only on an observed finalizeBlocks and an

advancing rollup currentL2BlockNumber. Submit Blobs only publishes data — it is not finalization.

When something fails

Read rules/debugging.md — it has a symptom → cause → fix table (RPC unreachable, gas too low, unfunded deployer, port collision, prover OOM, address mismatch, finality not advancing), the logs-first diagnostics, and timing expectations so "slow" isn't mistaken for "broken". Hard STOP conditions that need a human: an unfunded Sepolia deployer and repeated Sepolia gas/RPC failures.

When you change scripts or docs in this package

Read rules/making-changes.md — read-before-change, the validation gate (./scripts/check-quickstart-static.sh plus a real boot for boot-path changes), and the repo's commit rules that reject otherwise-fine commits: scope must be from the allowed list (use misc; lineth-stack is rejected), git commit -s for DCO, and a GitHub noreply author email or the push is blocked. Never commit .env, artifacts/, or any real secret.