README.md is 1144 lines across 30 ##/### sections, covering install, configuration (including scoped-token setup), every subcommand's usage, --json output, GitHub Actions integration, markdown page structure, and development. The in-progress work implementing _plans/025_file-organization.md is about to add more to it (a how-to subsection for moving/renaming files and setting up shared assets, plus a forthcoming standalone root-model doc that will need to cross-link into it) — the trend is more sections, not fewer.
The problem
A single file this size stops being something a reader skims to find one answer; it's something they Ctrl-F or give up on. Two audiences are mixed together in one document: someone installing and running a command for the first time, and someone debugging --json schema details or GitHub Actions credential wiring. The commands section alone (### create through ### schema) is roughly 600 lines by itself.
A rough split (not a commitment, just a starting shape)
- Keep in README.md: install, configure, a short usage overview, links out to the rest.
- One doc (or one per command group) for the
### create/update/fix/read/export/children/find/search/attachment-*/schema sections, which are largely reference material once you know markfluence exists.
docs/ci.md: the GitHub Actions section (credentials, workflow example).- A markdown-format doc for frontmatter/body conventions and page structure — possibly folded into the root-model doc
_plans/025's implementation is adding.
docs/json-output.md: the --json section, which is already schema-driven and dense enough to stand alone.
Not deciding here
Where exactly the lines land, whether README keeps stub sections with links or drops sections entirely, and whether this happens before or after the file-organization work lands (that work adds to README rather than restructuring it, on the theory that splitting docs and changing behavior shouldn't be the same diff).
README.md is 1144 lines across 30
##/###sections, covering install, configuration (including scoped-token setup), every subcommand's usage,--jsonoutput, GitHub Actions integration, markdown page structure, and development. The in-progress work implementing_plans/025_file-organization.mdis about to add more to it (a how-to subsection for moving/renaming files and setting up shared assets, plus a forthcoming standalone root-model doc that will need to cross-link into it) — the trend is more sections, not fewer.The problem
A single file this size stops being something a reader skims to find one answer; it's something they Ctrl-F or give up on. Two audiences are mixed together in one document: someone installing and running a command for the first time, and someone debugging
--jsonschema details or GitHub Actions credential wiring. The commands section alone (### createthrough### schema) is roughly 600 lines by itself.A rough split (not a commitment, just a starting shape)
### create/update/fix/read/export/children/find/search/attachment-*/schemasections, which are largely reference material once you know markfluence exists.docs/ci.md: the GitHub Actions section (credentials, workflow example)._plans/025's implementation is adding.docs/json-output.md: the--jsonsection, which is already schema-driven and dense enough to stand alone.Not deciding here
Where exactly the lines land, whether README keeps stub sections with links or drops sections entirely, and whether this happens before or after the file-organization work lands (that work adds to README rather than restructuring it, on the theory that splitting docs and changing behavior shouldn't be the same diff).