docs(readme): fix onboarding gaps found by the README self-setup e2e test#99
Merged
Conversation
…test Fixes #98 — six real gaps the new e2e-readme-onboarding.yml test consistently hit when following the README with no other context: - "From source" go install cannot work either casing: go.mod declares the module as github.com/tngtech/oh-my-agentic-coder but the repo lives at github.com/TNG/oh-my-agentic-coder. Replaced with the clone + `go build ./cmd/omac` recipe that omac-tng-installer's own install.sh already uses for exactly this reason (uses local module resolution, sidesteps the mismatch). Verified working end-to-end. - Homebrew now refuses an untrusted third-party tap; added the `brew trust tng-release/tap` step (lowercase, matching Homebrew's own tap-name normalization and the exact command its error message prints - confirmed against two real CI runs). - Ubuntu 23.10+/24.04+ restricts unprivileged user namespaces by AppArmor default, leaving a freshly apt-installed bwrap non-functional; documented the same AppArmor grant our own CI workflow (e2e.yml) already applies. - Quickstart's apt line was missing libsecret-1-0, despite the Prerequisites table listing it as required. - The documented apt download command (`-o omac.deb`) silently defeated the following checksum-verification step, since checksums.txt keys by the release's real filename; switched to `-O` to preserve it. - Noted that `omac doctor` reporting the built-in skill as "missing" before the first `omac start` is expected, not a contradiction of the "no separate step" auto-provisioning promise. Every fix here was independently reproduced (or reconciled against a known-good workaround in omac-tng-installer) rather than taken as-is from the agent's report. Signed-off-by: Niclas Hülsmann <niclas.huelsmann@tngtech.com>
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.
Summary
Fixes #98 — the six README gaps confirmed by the new
e2e-readme-onboarding.ymltest (#97) across two green runs, plus direct reproduction of each on this machine.Why
An agent given nothing but README.md repeatedly hit the same broken/incomplete steps while self-serving a normal omac dev setup. Each item below was independently re-verified (not just trusted from the agent's report) before being fixed.
How
go install):go.moddeclaresgithub.com/tngtech/oh-my-agentic-coder, but the repo lives atgithub.com/TNG/oh-my-agentic-coder— confirmed by directly runninggo installboth ways: lowercase 404s on GitHub, correct-case conflicts withgo.mod's declared path. Replaced with thegit clone+go build ./cmd/omacrecipe thatomac-tng-installer's owninstall.shalready uses for exactly this reason (its comment names the same mismatch). Verified the new recipe builds and runs cleanly end-to-end.brew trust tng-release/tapbetweenbrew tapandbrew install— lowercase, matching Homebrew's own tap-name normalization and the exact command both real CI runs report Homebrew's error message printing..github/workflows/e2e.ymlalready applies in CI, since a freshlyapt installedbwrapis non-functional there without it.libsecret-1-0: added to the Quickstart'sapt/dnflines (already required per the Prerequisites table, just missing from the one-liner).-o omac.deb) renamed the file away from whatchecksums.txtkeys by; switched to-Oto preserve the release filename.omac start, not a contradiction of the "no separate step" auto-provisioning promise.Verification
go installcommands directly — both fail exactly as described.omac versionruns.brew trustcasing cross-checked against both green onboarding runs' reports (https://github.com/TNG/oh-my-agentic-coder/actions/runs/29409220161, https://github.com/TNG/oh-my-agentic-coder/actions/runs/29409691842)..github/workflows/e2e.yml's existing, already-working step verbatim.Test plan
E2E README Onboardingafter merge and confirm the agent no longer needs to work around these six items (fewer/no matching entries in the "README gaps" section of its report).