Make the public README a product front door - #2
Merged
Conversation
Why: Strangers landing on the public repository saw an implementation changelog instead of a problem statement, install path, and hello-world. That blocked open-source use of an already-public Alpha. Changed: Rewrite README.md as a product page with audience, Alpha/macOS/Xcode status, use-versus-develop install, a five-minute hello-world, and a real Overview screenshot. Add docs/getting-started.md, docs/concepts.md, and docs/status.md. Contract docs/ in the specs manifest, spec-only profile, project-structure spec, and validate.sh. Add a front-door test that reads the shipped README and screenshot. Verification: npm run verify:public-surface npm run agent:verify -- --profile spec-only --paths README.md,docs/getting-started.md,docs/concepts.md,docs/status.md,docs/images/macos-overview.png,docs/test/front-door.test.mjs,spec/README.md,spec/project-structure.md,spec/build-and-test.md,.agents/manifests/specs.yaml,.agents/verify/spec-only.yaml,scripts/validate.sh --session-dir task-sessions/20260817-public-front-door Affected: README.md docs/getting-started.md docs/concepts.md docs/status.md docs/images/macos-overview.png docs/test/front-door.test.mjs spec/README.md spec/project-structure.md spec/build-and-test.md .agents/manifests/specs.yaml .agents/verify/spec-only.yaml scripts/validate.sh Refs: https://github.com/fiveonecode/simulator-broker spec/project-structure.md spec/build-and-test.md Session: task-sessions/20260817-public-front-door
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.
The public landing page was an implementation changelog. This PR is step 1 of making Simulator Broker usable by a stranger: rewrite the README as a product front door, add newcomer getting-started and concepts docs, and embed a real Overview screenshot.
What changed
README.mdnow states the iOS Simulator coordination problem, the audience, Alpha / macOS / Xcode status, use-versus-develop install, and a five-minute hello-world.docs/getting-started.md,docs/concepts.md, anddocs/status.md(the old status dump moved off the first screen).docs/images/macos-overview.png.docs/is contracted in the specs manifest, spec-only profile, andvalidate.sh.docs/test/front-door.test.mjsreads the shipped README and screenshot.Out of scope
Human CLI help, CLI-only install, Homebrew, releases, issue templates, and public test CI stay for later PRs.
Verification
npm run verify:public-surface(twice, both passed)npm run agent:verify -- --profile spec-onlypassed, including the new front-door testnpm run agent:completepassed fortask-sessions/20260817-public-front-door