yonatangross/orchestkit

What 15 HTML pages under docs/ (playgrounds, PR playgrounds, Lab copies) carry the clipboard fallback string selected, press Cmd+C, shown when navigator.clipboard.writeText is denied. On Windows and Linux the displayed shortcut is wrong. Raised by CodeRabbit on #3973 line 276; the same string is in every page generated from the shared explainer template, so fixing one page is not a fix. Fix Two lines in the template plus a sweep of the 15 existing files: const mod = /Mac|iPhone|iPad/.test(navigator.platform) ? 'Cmd' : 'Ctrl'; btn.textContent = `selected, press ${mod}+C`; Or the neutral wording "selected, copy it" with no shortcut at all, which is one string and never wrong. Where git grep -ln "press Cmd+C" -- 'docs/**/*.html' lists the 15 (as of main 1e59fb1). The source template is the glyph explainer template outside this repo (~/.claude/skills/glyph/templates/explainer.html), so the template fix is a hq-ext/user-skill change and the sweep is this repo's. Refs #3973, #3985.

Problem When the build-drift gate fails, it prints: ::error::Build drift detected! Run 'npm run build' and commit the changes (plugins/ src/hooks/dist/ README.md docs/site/lib/generated/) That tells you a directory list, not what you did wrong. The most common cause, by a wide margin, is editing a file under plugins/ instead of its source under src/. The message never says so. Real case: #3495, where an outside contributor edited plugins/ork/skills/api-design/scripts/problem-detail-exceptions.py and had to be told by hand that the source lives at src/skills/api-design/scripts/problem-detail-exceptions.py. Proposal In .github/workflows/ci.yml, in the Check for uncommitted build changes step, when the drifted set includes a path under plugins/ork/skills/, also print the corresponding src/ path. The mapping is mechanical: plugins/ork/skills/<rest> -> src/skills/<rest> Something like: git diff --name-only -- "${GENERATED[@]}" | while read -r f; do case "$f" in plugins/ork/skills/

Problem .github/ISSUE_TEMPLATE/config.yml has no pointer to the newcomer-friendly work. Someone arriving at the issue tracker sees 91 open issues with no signal about where to start. Proposal Add a contact_links entry to .github/ISSUE_TEMPLATE/config.yml pointing at the filtered label view, for example: contact_links: - name: Good first issues url: https://github.com/yonatangross/orchestkit/labels/good%20first%20issue about: New here? These are scoped, self-contained, and reviewed quickly. Check the existing config.yml for what is already configured and match its style rather than replacing it. Scope One file, .github/ISSUE_TEMPLATE/config.yml. Good first issue notes .github/** is on the CI playground gate's INERT list, so a PR touching only this file does NOT require an HTML playground.

Problem CONTRIBUTING.md explains the repo layout and the build, but never walks through a complete first pull request. The one thing a newcomer most needs, "I want to change this line, what exactly do I do", is not written down. This is the gap behind #3495: an outside contributor edited a generated file because nothing showed them the source-then-build loop end to end. #3498 fixed the incorrect statements, but there is still no worked example. Proposal Add a short "Your first pull request" section with one concrete, real example followed all the way through. Suggested shape: Find the file under src/ (not plugins/, which is build output) Make the change npm run build git status, showing that BOTH the src/ file and its regenerated copies appear, and that all of them get staged Commit with a conventional-commit title (note the 72-char limit, which the pre-commit hook enforces) Push and open the PR Worth calling out explicitly, because each has bitten someone: editing plugins/ instead

Problem pyproject.toml excludes two directory patterns from ruff: exclude = [ ... # Templates are educational examples - prioritize clarity over strict linting "skills/*/templates", "skills/*/examples", ] Neither matches anything. Verified at HEAD: $ find src/skills -path "*/templates/*.py" -o -path "*/examples/*.py" | wc -l 0 $ find src/skills -name "*.py" | wc -l 51 The patterns are root-anchored, but the files live under src/skills/... (and the generated copies under plugins/ork/skills/...). So the intent, spare educational example code from strict linting, has never taken effect. Why it matters It is a silent no-op that reads as coverage. Anyone adding lint enforcement (see #3500) would assume examples are already exempt when they are not. The fix Decide which is true and make the config say it: The exemption is still wanted: re-anchor the patterns so they actually match (for example src/skills/*/templates, **/skills/*/templates), or The exemption is obsolete: del