Read project-wide settings from markfluence.yaml

[willkg]

Closes #100. Unblocks #139, which builds pages: on this loader.

markfluence.yaml has been a bare root marker whose existence was its whole meaning. It now declares project-wide defaults — space and page_width — resolved flag > frontmatter > project file, so the answer closest to the content wins. The design is in _plans/038_project-file-settings.md.

The keys are the small half. space feeds one call site in create, page_width feeds resolveWidth in create and update. Almost everything interesting is in the loader and in what it refuses.

A file that cannot be understood stops the command

An unparseable file, or one holding an unrecognized key, is an error naming what is wrong — and it is specifically not treated as a valid root marker. Discovery does not walk on to an ancestor that happens to have a good one, and does not fall back to the markdown file's own directory. The root decides every attachment name, bounds every read, and anchors the link index, so a project file that cannot be understood means the project's boundary is unknown, and guessing is worse than stopping.

Refusing an unrecognized key is the point rather than a cost. A silently ignored spce: ENG is wrong for every file in the project at once, and a markfluence.yaml written for a newer markfluence holds keys an older binary would ignore — so the file carries no schema version, deliberately, and the error says an older binary is the likely cause:

markfluence.yaml:1: unknown setting "spce" (known: page_width, space) -- an unrecognized setting may mean this project needs a newer markfluence

Loading happens in open(), the single place a Root is built from a marker hit, so Discover, Cache.walkAndCache and FromPath cannot come to disagree about the rule. An empty file and a comment-only one stay valid — that is what ships, what the README documents, and what export plants.

Five facts from the code that shaped it

• open() is the single construction site for a Root from a marker, which is why the load lives there rather than in three places.
• internal/project cannot import internal/pagewidth — pagewidth imports client, and client.ResolveOptions.Roots is a *project.Cache. So the loader validates structure and a value's vocabulary is checked where it is consumed, plus a new offline lint in check.
• loadEnvFile swallowed discovery failures. Harmless while the file was never read; now it would silently resolve .env from the working directory instead of the project root, and would leave a command with no per-file root of its own (read, search, info) never reporting the malformed file at all. Fixed. --env-file still overrides absolutely, pinned by a test.
• update resolved width before it resolved the root, so the root moves up — the walk is cached, and building the index did not move, so a file the mtime check skips still never pays for one.
• update never reads space from the file (r.space comes from the live page), so a project-wide space: reaches only create until update: enforce space/parent and support page moves #10.

The one behavior change

A project-wide page_width: makes update assert a width on a file that declares none, where before the live width was left alone. Deliberate — it is what "declared means asserted" (L9) means one level up — and a project that wants the live width untouched omits the key, which keeps "absent means no width request at all" intact.

What it deliberately does not hold

No url, username, or token, and the reason is sharper than "those are credentials" (which #100 gives, and which invites relitigating since a site URL is not secret — it is why --cloud-id may be a flag). markfluence sends basic auth to whatever host the resolved URL names, so a url: in a committed, walked-up file would decide where CONFLUENCE_TOKEN is sent: one line in a pull request would redirect a CI run's token to a host of the author's choosing. That is a worse version of the .env hole #136 records, worse because this file is committed, shared, reached from a subdirectory, and reviewed as content rather than as configuration.

The asymmetry against the settings it does hold is the whole argument. A wrong space publishes to the wrong place in your own instance — visible, and fix recovers it. A wrong url hands out the token; neither.

One copy of the YAML dialect

internal/frontmatter now exposes Dialect.ReadMapping for a document with no --- fences, and internal/project reads through it. Every rule there was found by probing the pinned goccy — the scalar node-kind whitelist, the single-line rule, the null spellings, the flat-mapping refusal — so a second parser for a second file would be a second set of the same bugs, which is the "third minimal parser" #100 warned about and declined. What the package really owns is markfluence's YAML dialect; the fenced block is one use of it.

Two things stay frontmatter's own: the --- position shift (a whole file needs no correction) and scalarFields, the keys that must not hold a sequence — which a project file has no equivalent of and which #139's pages: entries will need to allow. The two nouns a diagnostic uses became a parameter, because frontmatter must be a flat mapping and setting "space" must be a single scalar value are both right and neither noun works in the other's sentence. Every message frontmatter itself emits is unchanged, pinned by its existing 800-line test file.

Verified live

Against the personal space on mozilla-hub.atlassian.net; the page was purged afterwards.

create with only a project-wide space:	published to ~60c36d07…, page_width: wide taken from the file
update on a file declaring no width	asserted narrow from the project file
unknown key	the message above, exit 1
invalid project page_width	caught offline by check, naming markfluence.yaml rather than the markdown file
--debug	project file …/markfluence.yaml: space=ENG, page_width=wide

A project-wide default is invisible by construction — it takes effect for a file that says nothing about it, so "why did this publish to ENG?" has no answer in the file the reader is looking at. --debug is where that answer goes. No --json or schema change: these are inputs, not results.

Two things the work turned up

• A test fixture was writing the literal bytes into markfluence.yaml — cmd/attachmentupload's generic writeFile helper, reused for the marker. The new refusal found it.
• docs/markdown_file.md's page_width row was already wrong, claiming create and update both assert on every publish where update makes no width request at all for a file that declares none. Corrected while the row was being touched.

Settled during the work

• No space: in the marker export plants — redundant by construction, since every exported file already carries its own space: in frontmatter (pagedoc.Frontmatter) and frontmatter beats the project file. It would matter only for a file added later, and even then inconsistently, since an existing marker is never overwritten (S3).
• create --persist still writes the resolved space: back into the file. Left alone: the target workflow is CI updating existing pages, not creating them — a person creates the page and wires the repo up so a workflow can update it, which is markfluence.yaml pages: page metadata outside the markdown file #139's "CI updates; humans create". Not persisting a project-supplied value would make a file's frontmatter silently depend on where it sits, and markfluence.yaml pages: page metadata outside the markdown file #139 supersedes the problem by writing a pages: entry instead.
• A url: cross-check — the safe direction of that key, where the project file declares the site and markfluence refuses to publish when the resolved URL disagrees, fencing the token rather than directing it. Noted in the plan, not filed; it waits for someone to want it.

Docs

docs/root-model.md's project-file section is rewritten — its central claim was that nothing in the file is parsed — and the CVE-2022-24765 framing below it is tightened rather than dropped: the file is read now, still never executed, and nothing in it can redirect a credential. CLAUDE.md gains an internal/project bullet, which it had none of at all — the same gap the last refresh found. docs/guarantees.md notes that an on-disk declared default sits inside L2's scope in the direction L2 wants, and is strictly better for it than the --space flag it replaces; status unchanged. --help had two stale claims, so docs/commands/ regenerates.

[willkg]

Adversarial review found seven real findings; all are fixed in 6 follow-up commits. Two were merge blockers, and the first is a correction to this PR's own description.

1. The frontmatter refactor was not behavior-preserving, contrary to what I claimed above. Threading Item into the flat-mapping refusal changed a user-facing string:

-frontmatter must be a flat mapping of key: value pairs, found String
+frontmatter must be a flat mapping of frontmatter: value pairs, found String

That lands verbatim in check --json. It survived because the existing assertion matched the substring "flat mapping", which both spellings contain. Item names a named key (setting "space" must be …) and reads as nonsense in a sentence about keys in general, so that word is literal again for both dialects — byte-identical to main. TestParseErrorWordingIsExact now pins every message frontmatter composes as a whole sentence; goccy's own parse errors stay out of it, since pinning a dependency's wording would make a goccy bump look like a markfluence regression.

2. check's new lint was a false positive. It reported an invalid project-wide page_width as Broken for every file under the root — including a file declaring its own width, which wins, so update publishes it fine. The comment justifying the severity ("fails every publish under this root") was false against the very resolvers the lint previews, and CLAUDE.md's rule for check is that a false positive is worse than a miss. Now reported only for a file whose frontmatter declares no width — exactly the set that would use the default.

3. --debug reported the wrong root, for commands that read no settings. ui.Debug fired inside loadConfig, and loading happens once per root for two unrelated reasons — a markdown file's root, and the separate walk from the working directory that only locates .env. So info --debug announced a project file it never consulted, and create described cwd's root rather than any file's. Reporting moved to project.ReportSettings(cache), an explicit call beside where each command already prints root:. Loading prints nothing, pinned by a test. This also answers the layering objection: a low-level package no longer prints as a side effect of doing its job.

4. --root re-read the project file once per starting directory. Cache held the override Root under abs only, so each new directory re-ran FromPath — a second os.OpenRoot (already true before this branch) and now a second file read, for a root that cannot differ. Cache.overrideRoot builds it once, and Close dedupes by *Root so a shared handle is not closed N times.

5. A UTF-8 BOM was diagnosed as "needs a newer markfluence." A file a Windows editor wrote reported an unknown setting whose name began U+FEFF. Stripped, at the start of the file only — anywhere else it is content markfluence must not silently discard.

6. attachment-upload reported a ConfigError the old way — wrapped as resolving the documentation root, coded IO — contradicting the CLAUDE.md bullet this branch adds. Now badInput/VALIDATION, matching create, update and check.

7. The reorder in update changed roots reporting for an all-skipped batch. It used to report none, since no file reached the root resolve. Defensible either way — roots means every distinct root the command resolved, and it did — but it was unrecorded, and now it is.

Test quality

Two findings there, both fixed.

TestRunProjectDefectIsScopedToItsOwnRoot was trivially true: it named only the good project, so nothing would touch the bad tree under any implementation. It now names both files in one run and asserts exactly one fails and that the good file is never blamed for the other project's width.

Nothing pinned update making an actual width request from a project default — only resolveWidth's apply bool, one layer above where the behavior change lives. Three tests now assert on the content-property traffic: two writes for a file declaring none (both the published and draft appearance properties, or the reader and the editor disagree), no requests at all when the project declares no width, and the file's own value on the wire when it declares one. Sabotage-checked — flipping apply to false fails the first.

Also

CLAUDE.md and docs/guarantees.md still cited scalarValue/elementValue, renamed by the refactor. _plans/038 records all seven findings with what each one broke, so the next change here starts from the evidence rather than from the claims.

What the review checked and found sound: the loader, the abort rule, walkAndCache's backfill past a malformed marker, items/maps against the old toMaps (identical partitioning, List nil-vs-empty preserved, a key in exactly one map), Item.Line, the precedence chain in all three resolvers including blank/whitespace/null at each level, apply on every error branch, --env-file overriding absolutely, and D4's empty/comment-only/declared-but-empty cases.

make check clean.