Skip to content

docs: STE100 pass over README, CONTRIBUTING, and docs/ - #187

Open
willkg wants to merge 16 commits into
mainfrom
docs-improvements
Open

willkg wants to merge 16 commits into
mainfrom
docs-improvements

Conversation

@willkg

@willkg willkg commented Sep 22, 2026

Copy link
Copy Markdown
Member

Part of #165.

Replaces #183, which GitHub closed when its head branch was renamed from readme-fix to this one.

An ASD-STE100 (Simplified Technical English) pass over seven documents, plus the corrections that reviewing them turned up.

README.md

  • STE100 rewrite: short sentences, active voice, no gerund headings, no em dashes. Every code block, link target, and table row is kept.
  • Restores details the rewrite dropped or changed: round-trip reassurance, the Homebrew completions note, the --root scope (diff redirects .env too, check honours the per-file root), find returning folder ids, and the .env warning firing on any group or world bit.
  • Fixes claims that were already wrong on main: moving an asset keeps its attachment (the name is the base name), the error-code list was missing CONFLICT, the schema example was missing space-info and user-info, and the create workflow used two different filenames.
  • Says that the divergence refusal and the unchanged-body skip both need a markfluence.yaml, and tells one-file-at-a-time users what they give up without one.

CONTRIBUTING.md

  • STE100 rewrite. It keeps the welcome and the reason for recording Confluence findings in their original shape on purpose.
  • Lists docs-check among what make check runs.

docs/guarantees.md

  • STE100 rewrite of the prose. Every id, label, status, code identifier, and reference is unchanged.
  • Corrects three stale claims against the code: the L3 statement (identity follows the file name, not the location), the orphaned-attachments reason, and the withinRoot paragraph in Symlinks. It also records the upload race (Attachment upload reads outside the os.Root that checked it #186) as a known limit of S2.

docs/json-output.md

  • STE100 rewrite. Checked against the schema, the review fixes: CONFLICT added to the error codes; export's status verbs (it never emits failed) and its multi-page results under --depth/--space; when body_changed and page_status are null; space-info, user-info and children --space reporting failure on stderr; an empty command on a bad-flag error.

docs/markdown_file.md

  • STE100 rewrite. The long notes for parent, labels, page_width and page_status move out of the field table into a subsection each.
  • Review fixes: create refuses a --space that disagrees with frontmatter, so flag > frontmatter holds only for width; title is optional for update; page_status is a single-value field; create writes page_width back, so a later update asserts it; a .md parent can be a page published earlier; doc links resolve to any .md under the root; <!-- bg:COLOR --> is a second comment directive.

docs/releasing.md

  • STE100 rewrite; the workflow's run in step 4 becomes a numbered sequence.
  • Review fixes: the binary prints the version without the v; the Homebrew check runs the cask binary by full path so a make install build on PATH cannot answer; the rehearsal's go mod tidy and make completions hooks; make check and the final publish are workflow steps, not goreleaser; recovery when no draft exists, or when only the publish step failed.

docs/root-model.md

  • STE100 rewrite. The four headings other documents link to are unchanged.
  • Review fixes: update does depend on the log for its two checks; --no-persist still writes a log line; a link outside the root is LINK BROKEN, and check exists; an image resolves relative to its page; an attachment's name is its base name, so moving an image keeps it; diff also redirects .env under --root; preflight converts before reserve; info is page-info.

Each of these four files has two commits: the rewrite, then the fixes from a code review of it.

_plans/048_principles.md (on main) plans reshaping guarantees.md into design principles with no statuses, so these status corrections are the last of that kind.

Review of the STE100 rewrite found places where it changed or lost
something a reader needs, plus errors that predate it:

- round trip: restore the missing verb and "content survives"
- batch publish: an unchanged page gets no new version, but it is not
  free of requests
- --root: diff redirects .env too, and check honours the per-file root
- find: it resolves to folder ids as well as page ids
- Homebrew completions: say there is nothing more to do
- moving assets: an attachment is named by its base name (_plans/029),
  so a move keeps it and only a rename orphans the old one; a page
  referencing two assets with one base name is refused
- error codes: add CONFLICT
- schema example: add space-info and user-info
- create workflow: use one filename throughout
Short sentences, active voice, no gerund headings, no contractions or em
dashes. Two lines keep their original shape on purpose: the welcome, which
is warm by design, and the reason for recording Confluence findings, which
loses its point in STE100.
CONTRIBUTING named vet, fmt-check, test, build, and lint, and left out
docs-check, which the Makefile runs between fmt-check and test.
- find: a folder id is also the target of children and export, not
  only a parent
- .env warning: any group or world permission bit fires it, not only
  read
- move an asset: drop the L3 citation, whose one-line statement still
  says identity follows location
- the divergence refusal and the unchanged-body skip both need the
  action log, which only exists under a markfluence.yaml; say so, and
  tell one-file-at-a-time users what they give up without one
- archive: it also holds completions/
- Location of documentation: include usage, and drop "additional"
- rewrap two lines past 80 columns
Prose only: every id, label, status, code identifier, issue and plan
reference, measured date, link target, and the WalkDir block are
unchanged. The table statements are reworded without changing meaning,
and the L5 note's quotation of its own law follows the new wording.

Known stale content is carried over as-is and corrected separately.
- L3: the statement said identity follows the asset's location. It
  follows the file name: convert.AttachmentFilename returns the base
  name, and planAttachments matches by that name and restamps a moved
  asset's recorded path. Statement corrected; label and status (Holds)
  unchanged. The note now cites the code rather than a plan.
- Orphaned attachments: identity is the file name, and #99 tracks the
  prune; the README no longer tells anyone to remove them by hand.
- Symlinks: convert.withinRoot no longer exists; images are checked
  through root.FS, an os.Root. Record the remaining limit: the upload
  opens an ordinary path, so a directory swapped for a symlink between
  the check and the upload is a race S2 does not cover.
Prose only: every code block, backtick token, link target, and issue
reference is unchanged.
Prose only: every code block, backtick token, link target, and swatch
value is unchanged. The long notes for parent, labels, page_width, and
page_status move out of the field table into a subsection each, since a
table cell cannot hold a 15-sentence paragraph under STE100's limits.
Prose only: every command, code block, link target, and issue reference
is unchanged. The workflow's run in step 4 becomes a numbered sequence.
Prose only: every code block, backtick token, link target, and issue,
plan, and CVE reference is unchanged, and so are the four headings other
documents link to. The pages: heading keeps its em dash, because the
anchor #pages--page-metadata-for-a-pristine-file is derived from it.
Checked against schema/json-output/v1.json:

- user-find truncated: the rewrite said there are no other matches; it
  means they cannot be counted
- error codes: add CONFLICT
- status verbs: add export (wrote, skipped, "" and its attachment
  verbs), which never emits failed; name children's status field as
  content status, not a verb
- export can report more than one page under --depth and --space
- attachment-*: a page lookup failure is a single failure with page_id
  and no filename
- body_changed is also null with no base or a base with no sha
- page_status null means different things on update/create and on
  page-info/read
- space-info, user-info and children --space also report failure as a
  stderr error object
- a bad-flag error object can have an empty command
Checked against the code:

- space: create refuses a --space that disagrees with frontmatter
  space (resolveSpace), so flag > frontmatter holds for page_width only
- title: update keeps the live title when it is absent; create needs
  it or --title, and an empty title fails both
- page_status is also a single-value field (scalarFields)
- create writes title and page_width back, so a later update asserts
  the width it chose
- a .md parent can be a page published earlier, and must be inside the
  root and not a symlink (parentPublished)
- doc links resolve to any .md under the root, not only siblings
- <!-- bg:COLOR --> is a second comment directive
- restore meanings the rewrite changed: which unresolved links are
  reported, raw storage passing through unconverted, list tags written
  like <br>, and storage recording cells as paragraphs
Checked against .goreleaser.yaml, release.yml, buildinfo and the
Makefile:

- verify step: the binary prints the version without the v
  (ldflags {{.Version}}); the rewrite turned "not markfluence
  --version" into an order the next block broke, and the reason given
  was backwards. The Homebrew check now runs the cask binary by its
  full path, since a make-install build earlier on PATH would answer
- rehearsal: goreleaser's hooks run go mod tidy and make completions,
  so clean completions/ too and check git status
- step 4: make check and the final publish are workflow steps, not
  goreleaser
- recovery: no draft exists when the run fails before goreleaser
  creates the release; a failed publish step needs only a re-run of gh
  release edit; the prose now names the cask branch
- wording the rewrite changed: the release job (not you) pushes the
  cask branch, skip_upload stops the cask push, and admins cannot
  force a merge
Checked against the code:

- the log: the rewrite said nothing depends on it; update's moved-page
  refusal and unchanged-body skip both do, though no run fails for want
  of it
- --no-persist still appends an action-log line (recordAction checks
  only dry-run)
- a link outside the root is replaced with LINK BROKEN, not left as
  written, and check (#42) already audits a tree offline
- an image resolves relative to its page's directory; the root only
  bounds it
- an attachment's name is its base name, so the root decides its
  recorded path, not its name; moving an image keeps its attachment
- diff also shares its root cache with .env resolution; create, update
  and attachment-upload are the commands that print the root
- preflight converts every file before reserve (#127)
- page_status is graded with title, page_width and labels
- info is page-info
@willkg willkg changed the title docs: STE100 pass over README, CONTRIBUTING, and guarantees docs: STE100 pass over README, CONTRIBUTING, and docs/ Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant