Quickstart documentation omits the shipped --enable-core-manual-close flag

[kalepail]

Note

Automated notice: Stellar Raven filed this issue from its automated evaluation pipeline. The issue includes evidence and a public source record. Please verify the live surface before you act.

Finding

The Quickstart container supports a manual ledger-close mode. The
stellar/quickstart start script parses --enable-core-manual-close and
writes the value into the generated etc/stellar-core.cfg.

Stellar Docs do not document the flag. The site holds a full Quickstart
section at /docs/tools/quickstart/, including advanced-usage/container,
advanced-usage/operation-modes, and advanced-usage/run-command-examples.
None of those pages names the flag. A repository-wide search of
stellar/stellar-docs for the exact string returns zero results.

Docs search cannot recover the flag either. A live search for the flag name
returns only ledger-ingestion pages.

Deterministic ledger close is a common local-test requirement. A developer who
needs it today must read the Quickstart shell script. The Quickstart section
already undertakes to document the container's run options, so this is an
omission on an existing page family.

The related count behavior is a separate upstream request. Stellar Core issue
4040, "Support manual closing N ledgers", is open. A manual close advances one
ledger per call today. Documentation should state that limit rather than imply
a count parameter exists.

Evidence

The code search, the live docs search, and the source reads all ran on
2026-08-14.

The stellar/quickstart start script carries these three lines:

: "${ENABLE_CORE_MANUAL_CLOSE:=false}"
    --enable-core-manual-close)
  run_silent "finalize-core-config-manual-close" perl -pi -e "s/__MANUAL_CLOSE__/$ENABLE_CORE_MANUAL_CLOSE/g" etc/stellar-core.cfg

Additional recorded evidence:

• 2026-08-14 code search over stellar/stellar-docs for "enable-core-manual-close" returned zero results
• 2026-08-14 read of stellar/quickstart start script shows the flag ships today; line 47 sets ENABLE_CORE_MANUAL_CLOSE=false, line 202 parses --enable-core-manual-close, and line 520 writes it into etc/stellar-core.cfg
• 2026-08-14 live stellarDocs.search_docs for "enable-core-manual-close quickstart manual close ledger" returned eight hits, all about LedgerCloseMeta ingestion, and none about the flag
• 2026-08-14 read of the stellar/quickstart README found no manual-close documentation either
• eval round 2026-08-14, main stamp 2026-08-14T03-56-23-variantA, row q-quickstart-manual-ledger-close

Recommendation

Add --enable-core-manual-close to the Quickstart run options on
/docs/tools/quickstart/advanced-usage/. Give the flag name, the default value
false, and the Stellar Core setting it controls.

Add one run-command example that starts a local network with the flag enabled.

State that one manual close advances one ledger, and link Stellar Core issue
4040 for the pending count request.

Source Record

Raven recorded this finding as sd-044 (stellar-docs, discovered 2026-08-14).

Public source record: improvements/stellar-docs/sd-044-quickstart-manual-close-flag-undocumented.md

Immutable source snapshot: dbc466e55105

Resolution Handoff

When you deploy a fix, link the resolving issue or pull request to the source record.
Then notify Raven through:

https://github.com/stellar-experimental/stellar-raven/issues/new?template=upstream-improvement-ready.yml&title=%5Bupstream-ready%5D%20sd-044%3A%20

Include the finding ID and the resolving issue or pull request.
Include the deployed version or timestamp. Include the smallest live recheck.
Raven verifies the live surface before it sets the finding to fixed-upstream.
An issue closure or merged pull request does not prove the fix.
A separate reviewer repeats the live check before Raven retires the active finding.
Raven keeps a commit-pinned snapshot when one is available.

[devtechedge]

Hi, I'd like to work on this.

I plan to add --enable-core-manual-close to the Quickstart advanced usage pages with the flag name, its default value of false, and the Stellar Core setting it controls, plus one run-command example showing a local network started with the flag enabled.

I'll also state that one manual close advances a single ledger today, with a link to Stellar Core issue 4040 for the pending count request.

Once the PR is up I'll link it here and file the Raven upstream-ready notice as described in the handoff section.

[kaankacar]

Working this because Raven filed it (label raven).

I verified the finding. The stellar/quickstart start script parses --enable-core-manual-close at lines 47, 202 and 520. No page under docs/tools/quickstart/ names the flag.

PR #2850 from @devtechedge documents it. I will not open a second PR.

One point for that PR. Stellar Core's HTTP port 11626 is separate from port 8000, as the Ports page shows. The new run-command example publishes only 8000, so the manualclose request cannot reach the container. The example needs -p "11626:11626" too.

After #2850 merges, this issue still needs the Raven sd-044 handoff.