feat(compile): make the ## Sources section optional

[LorenzoGentile]

What

llmwiki compile --no-sources-section, or LLMWIKI_SOURCES_SECTION=off, stops page generation from asking the model for a trailing ## Sources section. Unset preserves the prompt byte-for-byte.

Why

It is a third copy of the same list. A compiled page already carries its provenance twice: the sources: frontmatter, which page-renderer.ts builds from entry.sourceFiles — the files the compiler actually read, not anything the model writes — and the inline ^[file.md:1-5] markers that carry it at paragraph level. A project that renders either of those in its own UI ends up showing the same list a third time in the prose.

Stripping it downstream does not hold. The heading is not a stable string. withLangLine appends Write the output in <lang>. to the same prompt that requests the section in English, so under --lang the model localizes that heading along with the rest of the page. A consumer matching on ## Sources silently stops matching the moment a project sets an output language. Suppressing the request is the only reliable way to not have the section.

That second point is not hypothetical — we hit it in a downstream integration that renders the frontmatter as a bibliography and had a post-processing step keyed on the literal heading.

Scope

## Sources appears exactly once in src/: the prompt line this PR makes conditional. Nothing parses it — the citation lint rules in src/linter/rules-citations.ts work on ^[...] markers, and the frontmatter and export envelope are built independently. So this removes an instruction and no downstream consumer changes behaviour.

PROMPT_VERSION

Left at v1, and I would like your call on it rather than assuming. The constant's contract says to bump when prompt wording changes in a way that could alter compiled page content. Here the default path is byte-identical, and PROMPT_VERSION was introduced (e9bdf48, June) into a page prompt that already contained the optional language directive (#46, April) — so v1 already denotes a contract with a user-selected modifier in it. Happy to bump it if you read that differently.

Design

Mirrors src/utils/output-language.ts: a small module holding the env resolver and an apply…Option helper for the CLI flag, read directly by the prompt builder. No threading through the compile pipeline, and the default case allocates nothing extra.

Commander gives --no-sources-section a default of true, so only an explicit false writes to the env slot. That keeps the variable authoritative for setups that configure the project rather than a single invocation.

How to test

npx tsc --noEmit
npm run build
npm test
npm run fallow:ci

test/sources-section.test.ts covers the resolver (default on, the four off spellings, trim/case handling, unknown values), the commander --no-x semantics including that a default true does not clobber an existing opt-out, and the prompt builder in both states — asserting that disabling drops the line rather than blanking it, and that the inline citation contract survives.

Full suite on this branch: 4874 passed, 3 skipped, no regressions. npm run fallow:ci: 0 above threshold, maintainability 90.2.

End to end:

llmwiki compile --no-sources-section
LLMWIKI_SOURCES_SECTION=off llmwiki compile

Docs updated in docs/cli/compile.mdx and docs/configuration/environment-variables.mdx, plus a CHANGELOG entry under Unreleased.

[ethanj]

Nice piece of work. The localization argument is the part that convinced me. withLangLine appends the language directive to the same prompt that asks for the section in English, so under --lang the model localizes the heading and a downstream matcher on the literal ## Sources quietly stops matching. That's not obvious until you go looking, and it's a real justification for suppressing the request rather than stripping the output.

The scope claim checks out too: ## Sources appears exactly once in src/, nothing parses it, and the frontmatter is built from entry.sourceFiles independently of what the model writes. And sourcesSectionLines() spreading rather than blanking is the right shape. The line-count assertion is a control that would actually catch a regression to "".

Two things before I merge, both small.

1. Bump PROMPT_VERSION to v2.

You were right to ask rather than assume, and I went back and forth on it. Landing on: bump it.

The way I read the field, it identifies the prompt implementation that produced a page, not the modifiers a given run chose. So v1 means "built by the implementation where ## Sources was unconditional" and v2 means "built by the one where it's conditional". That means a v1 page tells an auditor with certainty that the section was requested, where today it tells them nothing. The contract's own wording ("changes in a way that could alter compiled page content") points the same way, and the new branch satisfies it.

Your --lang precedent argument was a fair one, I just don't think it carries: when the constant was introduced doesn't establish the bump policy going forward.

Worth saying that this is free: PROMPT_VERSION isn't part of the compile fingerprint, so the bump triggers no recompiles. Pages pick up v2 only when they're regenerated anyway.

2. Add a CLI integration test.

test/output-language-integration.test.ts is the direct template. It spawns the CLI, asserts the directive reaches the system prompt, and covers the env-var and negative cases. Right now nothing in the test tree loads cli.ts, so deleting applySourcesSectionOption(options.sourcesSection) leaves the whole suite green. The harness is already there in test/fixtures/run-cli.ts.

One question, not a request. --lang wins over LLMWIKI_OUTPUT_LANG, but --no-sources-section can't override LLMWIKI_SOURCES_SECTION=off, because Commander doesn't synthesize a positive counterpart and the env var becomes a one-way door. Your reasoning for that is coherent and I can live with it, but the two flags now sit one row apart in the same docs table pointing opposite ways. Would you rather add --sources-section, or document the asymmetry? Your call.