Skip to content

docs(readme): local preview, prerequisites, owner-wording fix, polish - #19

Merged
mikim merged 1 commit into
mainfrom
docs/readme-polish
Jul 25, 2026
Merged

docs(readme): local preview, prerequisites, owner-wording fix, polish#19
mikim merged 1 commit into
mainfrom
docs/readme-polish

Conversation

@mikim

@mikim mikim commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

README-only polish. The README was already accurate (an adversarial review found 0 factual errors and 0 broken links across every claim — field lists, the 12-tier enum, the 7 chips, section names, all commands, both CI workflows, precedence subtleties). These changes close a few first-time-reader gaps and one wording inaccuracy, without touching its verified-accurate style. Every new claim was checked against the repo.

Substantive (recommended)

  1. Local preview — the README gave the generate + validate commands but never said how to view the rendered page, which is the whole product. Added a one-liner. Grounded: the generated index.html has 0 runtime fetches and inlined CSS, so open index.html works over file://.
  2. Prerequisites — no toolchain/versions were stated. Added them, grounded in what CI actually pins: Node 22 and Python 3.12 (.github/workflows/registry.yml lines 23/28); there is no package.json/.nvmrc, so CI was the only source. Also cross-referenced the pip install "jsonschema[format-nongpl]" prereq at the contributor walkthrough's validate step (it appeared only once before, so a reader following steps 1–6 could hit ModuleNotFoundError).
  3. Accuracy fix — the Files table described adoption.yaml as recording a "named human owner"; the human_owner is a maintainers body (MosslandOpenDevs maintainers), which the adoption file itself distinguishes from "a single named individual." Reworded to "the human owner (a named maintainers body)".
  4. Onboarding — a top-of-file "Contributing?" pointer to AGENTS.md + the add-a-service section (previously only in the Files table and a buried blockquote).

Stylistic (easy to drop if you'd rather not)

  1. Contents table (the doc is ~190 lines / 8 sections).
  2. CI badgesregistry.yml + assurance.yml. They visualize the README's central "CI enforces this" claim; drop them if you prefer the badge-free look.
  3. Nits — descriptive H1 (Mossland Verified Links instead of the repo slug); gloss 최종 확인 as "(last-verified)" to match the KR/EN pairing used everywhere else; fix a comma splice ("this, it is" → "this — it is").

Verification

  • All in-page anchors and file links resolve — 0 broken (checked every #anchor against the heading slugs and every relative link with test -e; badge workflow files exist).
  • README-only: no functional/site code, no generated file, no assurance artifact changed. The v0.5.0 adopter check stays exit 0 / 0 ERROR-WARN (README is not a validated artifact), and the drift gate sees no adoption/register change.

Review

Do not merge without owner review. Docs-only; nothing here is decided by the drafting agent. The substantive items (1–4) and stylistic items (5–7) are separated above so you can cherry-pick during review.

…olish

Improve the README for first-time readers and contributors while keeping its
verified-accurate style. Additive, grounded changes only — every new claim was
checked against the repo:

- Preview: how to view the rendered page locally (index.html is self-contained
  — 0 runtime fetches, CSS inlined), which was missing for a repo whose product
  is a rendered page.
- Prerequisites: state the toolchain — Node (CI pins 22) and Python 3 (CI pins
  3.12) for the validator; cross-reference the pip requirement at the
  contributor walkthrough's validate step so step-by-step readers don't hit
  ModuleNotFoundError.
- Fix (accuracy): the Files table said "named human owner"; human_owner is a
  maintainers body, not an individual — reword to "a named maintainers body".
- Onboarding: a top "Contributing?" pointer to AGENTS.md + the add-a-service
  section, and a Contents table for a ~190-line doc.
- Nits: descriptive H1 (Mossland Verified Links); registry + assurance CI
  badges; gloss 최종 확인 as "(last-verified)"; fix a comma splice.

README-only; no functional/site or assurance-artifact change. Verified: all
in-page anchors + file links resolve (0 broken); v0.5.0 adopter check stays
exit 0 / 0 ERROR-WARN.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@mikim
mikim merged commit 3ad5616 into main Jul 25, 2026
8 checks passed
@mikim
mikim deleted the docs/readme-polish branch July 25, 2026 01:00
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