Make README the project introduction; move component write-ups to docs/components.md - #248
Merged
Merged
Conversation
…nts.md README had grown to 943 lines, and 29 of its 36 sections were "## Inactive <component>" write-ups that construction PRs appended above the actual introduction. Everything a newcomer needs first — what ystack is, the team, the loop, the design decisions, the model policy, the layout, the rollout — started past line 640. README should be the project's introduction, so the write-ups move to their own file and README keeps a short index. What changed: - README is an introduction again (351 lines). It keeps the existing intro sections, adds a short construction-mode paragraph up top, and carries one compact "Components (all inactive)" index: one row per component with its exact section title, its path, a one-line description, and a link to its write-up. - docs/components.md is new. It holds all 29 "## Inactive ..." sections moved verbatim (same headings, same text, same order) behind a short preamble that says everything there is inactive and repo-only, and that a future construction PR adds its write-up there plus one row to README's index. - ci/required-files.txt lists docs/components.md, RESTORE.md points the restorer at it, and README's Layout block names it. The manifest entry is appended at the end of ci/required-files.txt rather than next to README.md in the top-docs block: portable-core-schema.test.sh pins a digest over the manifest's first 89 lines, so an insert there is a false failure. Proof: - bash scripts/check-rename.sh — clean. - No test changed. The six tests that grep README for exact strings pass alone: control-policy-set (61), control-foundation-rollup (23), control-duty-separation (56), control-evidence-integrity (75), portable-core-v2-fake-forge (45/45), portable-core-assembly (34/34 findings, 279/279 legacy assertions). - bash scripts/test/portable-core-schema.test.sh — failures: 0. - tail -n +22 docs/components.md is byte-identical to lines 19-644 of README on origin/main, so the write-ups moved without an edit. The moved sections carry no core generation id and no schema import, so docs/components.md needed no entry in the portable-core-schema allowlist. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Deploying ystack with
|
| Latest commit: |
f82bb13
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://ac1ce841.fabrica-6yx.pages.dev |
| Branch Preview URL: | https://ystack-docs-readme-as-introd.fabrica-6yx.pages.dev |
…-introduction # Conflicts: # README.md
Owner
Author
Codex reviewer (cross-vendor, read-only)Reviewed-head: 008fcb9 Posted verbatim by The refactor mostly preserves the README content in a new component document, but it accidentally drops the offline delivery replay component write-up and index entry. That is a substantive documentation loss for a restore-critical component. Review comment:
|
The delivery replay section reached README through the merge with main after this branch was cut, and the merge resolution dropped it. It now lives in docs/components.md in its original position with an index row in README. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Owner
Author
Codex reviewer (cross-vendor, read-only)Reviewed-head: f82bb13 Posted verbatim by The change moves the inactive component write-ups into a dedicated document, updates README/RESTORE references, and adds the new file to the required-files manifest. I did not find any correctness, restore, or link consistency issue introduced by the patch. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README.md had grown to 943 lines, 29 of its 36 sections being the "Inactive …" component write-ups that construction PRs appended above the actual introduction, which started around line 390. The operator asked for README to be the project introduction again.
What this does:
docs/components.mdholds every component write-up moved verbatim (same headings, text, and order;tail -n +22 docs/components.mdis byte-identical to lines 19–644 of the previous README), with a preamble stating the convention: future construction PRs add their write-up there and one index row to README.docs/components.mdtoo;ci/required-files.txtlists it (appended at the end because the schema guard pins a digest over the manifest's leading block); the Layout section names it and a stale "see below" was corrected.Nothing else changes. No test was modified: the six suites that grep README for exact phrases still find them in the index rows.
Note for the merge queue: PR #247 adds one more README section (alternative profile assembly); when it merges, that section moves to
docs/components.mdplus an index row.Proof run on e652e24:
bash scripts/test/portable-core-schema.test.sh→ failures: 0 (after commit)bash scripts/check-rename.shcleancmpof the moved text against the previous README slice🤖 Generated with Claude Code