Cut the README from 1534 to 531 lines, and make --help the command reference

[willkg]

README.md was 1534 lines. It is now 531 — a 65% cut with nothing deleted that wasn't duplicated elsewhere, better placed elsewhere, or already available from the binary. Fixes #102.

The shape it converges on: the README is a 50,000-foot view of what markfluence can do and which command to reach for. It is not a command reference — that is what markfluence CMD --help is for. Keeping both meant keeping both in step, which is the failure this issue was really about.

Where the lines were

Measured first, because the distribution mattered more than the total:

section	before	after
## Usage — per-command reference	832	200
## Markdown page structure	333	24
## Configure	141	105
everything else	228	202

--help becomes the reference

Cobra has an Example field for worked invocations and no command used it — the README was carrying content the binary had a dedicated, empty slot for. Every command now has one, and the Long descriptions absorbed what only the README said: create's page_id-that-resolves-to-nothing being a failure rather than a fresh page; update's never writing back, which is why fixing a wrong id is always safe; fix's canonical key order; read's lossy transforms making it a reading aid rather than a guaranteed round-trip.

## Usage is now which command to reach for, three common workflows, and the three output shapes worth seeing before you run them (children's indented tree, find's current/archived/folder split, search's hit blocks).

docs/commands/ is that help text rendered by cobra's own doc generator, so the reference is browsable and linkable on GitHub without installing anything. Generated and checked in — which is a second copy, and only acceptable because it cannot drift: make docs-check regenerates into a temp dir and diffs, and runs inside make check, the same role fmt-check plays for formatting. DisableAutoGenTag, or a timestamp would make every regeneration a diff and turn the guard into noise.

TestSubcommandsDocumentThemselves closes the loop. Once --help is the reference, a command added with a one-line Long and no Example is documented nowhere and nothing else would notice. It requires a length floor rather than non-empty, since "Create pages." satisfies non-empty and explains nothing.

What moved out

	lines	why there
docs/markdown_file.md	356	the page format — every frontmatter field and every body construct. These were two halves of one reference split across two files, and the moved half's intro had to say so
docs/json-output.md	82	the per-command --json detail. The schema is the authoritative contract but cannot carry reasoning — why check's broken has no error/code, why find/search report failures on stderr rather than as a result
docs/github-actions.md	79	a task you follow once while wiring up CI

What was deleted as duplication

### Scoped tokens carried a second copy of docs/confluence/api.md's scope material, and the README was the lossier copy — 3 occurrences of granular scope names against api.md's 12. A live drift risk, not a theoretical one: #91 required updating the README's scope table and code review caught that a row had been missed.

## Development duplicated CONTRIBUTING.md line for line, then ended by linking to CONTRIBUTING.md for the rest — the duplication was its own argument. It became a pointer, then went away once CONTRIBUTING.md earned a row in the index table.

Three command sections repeated their own --help almost verbatim before the wholesale move.

Structure

A "Location of documentation" table instead of a hand-written TOC. GitHub already renders an outline for any markdown file, so a TOC duplicates it and becomes one more thing to update — precisely the rot that made the scope table wrong. What GitHub's outline cannot index is the other files, and "where is the thing about X" is the actual question.

### Moving files and assets moved under ## The documentation root. It was top-level and next to "Common workflows" while being a different kind of thing: no commands in it at all, every entry a consequence of the root and identity model that section establishes.

Three things worth flagging

My estimate for the --help de-duplication step was wrong. I projected ~300 lines on #102 from "227 lines of --help prose exist" — which conflated existing with being duplicated. Hand-trimming three sections yielded 45. What actually delivered was moving the reference wholesale and letting --help own it.

Testing the drift guard found two bugs in it. make docs silently did nothing, because docs/ is a real directory and make considered the target satisfied — a missing .PHONY. Without sabotaging it deliberately I would have shipped a regenerate target that never regenerates. The failure message also needed to name the file.

A claim in the fix workflow was wrong and I checked rather than trusted it. A draft said fix adopts a page somebody "labeled or retitled" in the UI. plannedChanges fills title only when the frontmatter's is missing or blank, so a renamed page does not rename your frontmatter. The README now says that outright, because "reconciles the file to the page" invites exactly that assumption.

Also here

cmd.Root() is newly exported, for the docs generator alone — a main() inside package cmd would be built into the binary, and a _test.go that writes files into the repo is not a test. That is new public surface for a tooling concern, and worth a look.

CONTRIBUTING.md no longer asks a bug reporter which Confluence flavour they are on "since the API differs" — markfluence now states Data Center is unsupported, so asking invites a report we have said we cannot act on.

Docs and help text only — no behaviour change, and make check passes at every commit.