feat(contrib): contributor docs + repo-wide prose pass + intake templates#105
Merged
Merged
Conversation
Replaces the Tailscale magic-DNS hostname `pool.tail42ba87.ts.net:8081` with the generic `languagetool:8081` in the LANGUAGETOOL_URL default (scripts/prose-check.sh) and the matching prose-scrub example (RELEASES.md), plus a stale comment in scripts/hooks/pre-push. The Tailscale hostname identifies a private network host and should not live in committed artifacts. Consumers set LANGUAGETOOL_URL explicitly via env when their LT instance is elsewhere; the generic default is just a docs-readable placeholder.
Two contributor entry points land together: content/contribute.md renders as the visitor-facing /contribute page on anc.dev. Walks visitors through the three contribution tiers (pressure-test, propose alternative, code/docs PR), explains the cross-repo navigation across spec / site / CLI / skill, and sets honest response-time expectations for the solo-maintainer model. CONTRIBUTING.md is the GitHub-surfaced repo file that contributors land on when they click "Contributing guidelines" on the issue or PR form. Mirrors the same tier framing but scoped to the site repo specifically (rendered spec, leaderboard, live-scoring loop, scorecard pages, badge surface, skill-distribution endpoint).
The /check and /install copy claimed `anc` and `agentnative` were two aliases for the same binary. The brew formula and Cargo.toml confirm only `bin/"anc"` ships; the `agentnative` crate produces a single binary named `anc`. Strip the dual-binary prose; keep the package-manager commands (`cargo install agentnative`, `brew install ... agentnative`), which install the same `anc` binary. Install page title becomes `# Install anc` to match the binary the reader actually invokes.
…md to RELEASES-RATIONALE.md
Em-dash density reduction (per-occurrence judgment per unslop SKILL.md, no bucket substitution), write-good/proselint signal fixes, and Vale spelling vocab additions across 21 in-scope markdown files. Final state: 0 blocking, unslop score 0 across the set with 34 documented per-occurrence leaves (structural list-item labels, single em-dashes carrying real contrast, quoted-source text).
Styles YAML rule pack sources (`brand/*.yml`, `site/*.yml`) standardized on a single colon move for `# Source:` lines and parallel `message:` strings, then `styles/{brand,site}/README.md` regenerated via `scripts/generate-pack-readme.mjs` so the pre-push drift check stays green.
ARCHITECTURE.md renamed to RELEASES-RATIONALE.md to communicate the file's actual role: the WHY behind RELEASES.md (the runbook is its companion, not its standalone reference). Cross-references in `scripts/smoke-api-score.sh` header comment and `tests/wrangler-config.test.ts` describe-block + path constant updated to match.
The script was vendored from agentnative-spec where `styles/{brand,spec}/` is the canonical pack layout. This repo has `styles/{brand,site}/`, so the bare invocation `node scripts/generate-pack-readme.mjs` failed trying to read non-existent `styles/spec/`. Update DEFAULT_PACKS to `["brand", "site"]` and the usage header. Bare drift-check (`--check`) now passes.
Same defect audited in sibling repos: present in agentnative-cli (custom pack is `brand` only there; fix is `["brand"]`), absent in agentnative-skill (no styles/ dir, no script).
Pair with the /contribute site page and CONTRIBUTING.md added earlier on this branch. Expands `.github/ISSUE_TEMPLATE/config.yml` to route Tier-3 tool-registry submissions to the linter repo and adds an entry for the skill bundle. Adds a blank issue template for cases that don't fit any structured template.
CONTRIBUTING.md L106 and RELEASES.md L245 exceeded the 120-char limit after the rename touched their cross-references. Author-side line wraps applied; rendered output unchanged.
… anc` Regression #6 asserted the install page started with `# Install agentnative`. The page title was renamed in the dual-binary-framing fix earlier on this branch; the assertion now matches the new title.
14 tasks
brettdavies
added a commit
that referenced
this pull request
May 21, 2026
## Summary Exposes the two unreachable pages, fixes a build-registration bug that was silently 404ing `/contribute`, adds a four-repo Source row to the footer, and corrects a markdown formatting bug plus three near-dead deep links on the contributor page. ## Changelog ### Added - Nav exposes the `/skill` page (skill-bundle install) and the `/contribute` page; the header now carries eight plain-text items in reading order: Leaderboard, Install, Check your CLI, Skill, Methodology, Coverage, About, Contribute. - Footer Source row links the four canonical repos (`spec`, `cli`, `site`, `skill`) under a quiet GitHub icon kicker. Inline SVG matches the `currentColor` treatment of the existing AI-summary icons so theme switches and dark mode work without extra CSS. ### Fixed - `/contribute` was building no HTML or markdown twin because the content file shipped without a corresponding entry in `src/build/build.mjs` `subPages`. The route silently 404'd on the live worker. Adding the entry restores the page and adds it to `dist/sitemap.xml`. - `/contribute` bullet for `Add a tool to the registry` rendered with an orphan `-` and a stray paragraph below it. The link URL is long enough that the auto-format hook (`textwrap.fill` with `break_long_words=False`) couldn't keep bullet marker and link on the same 120-character line. Switched to a reference-style link so the inline bullet stays short. - Three `/contribute` references to `principles/AGENTS.md § Pressure-test protocol` linked to the top of the upstream file rather than the named section. All three now deep-link to `#pressure-test-protocol` so visitors land on the protocol prose (which also carries the `draft → under-review → active → locked` status-flip rules at lines 98 to 117). - `.site-nav` was breaking words inside a single link on narrow viewports (e.g. `Check your CLI` stacking as `Check` / `your` / `CLI`). Adding `flex-wrap: wrap` plus `white-space: nowrap` on the links fixes both the immediate eight-item layout and the pre-existing six-item bug. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) - [x] `fix`: Bug fix (non-breaking change which fixes an issue) - [ ] `BREAKING CHANGE`: Breaking API change (requires major version bump) ## Related Issues/Stories - Story: n/a - Issue: n/a - Architecture: n/a - Related PRs: builds on #105 (which added `content/contribute.md` and `CONTRIBUTING.md`) ## Testing - [x] Unit tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `bun test`: 736 pass, 0 fail (no test changes; existing assertions still hold). - `bun run lint`: 0 errors across biome and markdownlint. - `node scripts/generate-pack-readme.mjs --check`: passes (no `styles/` content changed). - Local browse via `bunx wrangler dev --env staging --local --port 8787`: visually verified header (8 items, light + dark, 480px narrow viewport wraps cleanly without intra-link breaks), footer Source row (GitHub icon kicker plus four repo links rendered between AI-summary block and meta line), and both newly-routed pages (`/skill` title `Install agent-native-cli`, `/contribute` title `Contribute`). - Build output: `dist/contribute.html`, `dist/contribute.md`, and a `<url>/contribute` entry in `dist/sitemap.xml` are all produced where the previous build emitted nothing. ## Files Modified **Modified:** - `src/build/build.mjs`: added `{ name: 'contribute', path: ... }` to the `subPages` array. - `src/build/sitemap.mjs`: added `/contribute` to the canonical paths list. - `src/build/shell.mjs`: added `Skill` and `Contribute` nav items, a `GITHUB_SVG` constant (Simple Icons mark), a `SOURCE_REPOS` list of four canonical repos, and the footer Source row markup. - `src/styles/site.css`: added `flex-wrap` and `gap` to `.site-nav` plus `white-space: nowrap` on `.site-nav a`; added `.site-footer__source` rules for the new row. - `content/contribute.md`: reference-style link for `add-tool-to-registry` template, three deep-link anchors on `principles/AGENTS.md` references. **Created:** - None **Renamed:** - None **Deleted:** - None ## Key Features - Header nav exposes every page that ships on the site; `/skill` and `/contribute` no longer require an out-of-band URL. - Footer Source row makes the four-repo architecture visible without requiring the visitor to read About or guess the org URL. ## Benefits - Visitors can reach every shipped page from any page; previously `/skill` was reachable only via the homepage's "Install agent-native-cli" CTA copy and `/contribute` was unreachable entirely. - The Source row sets the expectation that the standard lives across four repos (spec, cli, site, skill), which prepares visitors for the cross-repo pressure-test mechanism described on `/contribute`. - The nav-wrap fix removes a layout bug that affected every viewport narrower than the longest nav item. ## Breaking Changes - [x] No breaking changes No anchor changes, no removed routes. `/contribute` going from 404 to 200 is a Worker-observable change but not a user-facing breakage (404 was the bug; 200 is the fix). ## Deployment Notes - [x] No special deployment steps required The `paths-ignore` filter does not skip changes to `src/build/` or `src/styles/`, so a normal `dev → staging` worker deploy ships the build. ## Screenshots/Recordings n/a in this body. Visual verification covered in Testing above; screenshots reviewed locally under `bunx wrangler dev --env staging --local --port 8787`. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented) ## Additional Context Two `/contribute` intake URLs are known to 404 on the live web and were left as-is per direct instruction during review: - `agentnative-cli/issues/new?template=add-tool-to-registry.yml` (template file exists locally in the cli working tree as untracked, never committed, never pushed). - `agentnative/issues/new?template=grading-finding.yml` (template exists on `agentnative` `origin/dev` per PR #30 but not yet on `origin/main`; GitHub serves issue templates from the default branch). Both will resolve once their respective upstreams land. No site-side workaround was added.
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
Combines the contributor-docs work that opened this branch with the repo-wide prose pass and a few correctness fixes that surfaced during the pass. Four logical commits: dual-binary framing fix, repo-wide prose pass plus ARCHITECTURE rename, generate-pack-readme default fix, expanded issue intake templates.
Changelog
Added
CONTRIBUTING.md,/contributesite page, and expanded.github/ISSUE_TEMPLATE/routing for Signal, Proposal, and Code tiers across the spec, linter, site, and skill repos. A blank-issue template covers cases the structured forms don't fit.Changed
/installpage title now reads "Install anc" to match the only compiled binary. Dual-binary framing dropped from/installand/check(the brew formula andCargo.tomlproduce a single binary namedanc; the crate nameagentnativeand the brew formula nameagentnativeinstall the same binary).Fixed
scripts/generate-pack-readme.mjsDEFAULT_PACKScorrected from["brand", "spec"]to["brand", "site"]. The previous default was a vendor-from-spec leftover that made the bare invocation exit 1 trying to read non-existentstyles/spec/.Documentation
ARCHITECTURE.mdrenamed toRELEASES-RATIONALE.mdto reflect its role as the WHY companion toRELEASES.md(the runbook). Cross-references inscripts/smoke-api-score.shandtests/wrangler-config.test.tsfollow the rename.Crowdsourced).Type of Change
feat: New feature (non-breaking change which adds functionality)fix: Bug fix (non-breaking change which fixes an issue)docs: Documentation updateBREAKING CHANGE: Breaking API change (requires major version bump)Related Issues/Stories
RELEASES-RATIONALE.md(renamed fromARCHITECTURE.mdin this PR)Testing
Test Summary:
bash scripts/prose-check.sh: 0 blocking, 1296 warning (down from 1 blocking, 1314 warning at branch start). Remaining warnings are LT typography misfires on markdown tables (whitespace, arrows) that the script deliberately keeps non-blocking.~/.claude/skills/unslop/scripts/score.pyacross all 24 in-scope files: 21 files at score 0; 3 files retain documented per-occurrence leaves (/checkscore 6,/introscore 7, PR template score 4) where a single em-dash carries real contrast and removing it would weaken the prose.node scripts/generate-pack-readme.mjs --check: passes on bare invocation.tests/wrangler-config.test.tsupdated for theRELEASES-RATIONALE.mdrename; assertion still grep-matches the canonicalscores/{binary}/{anc-version}.jsonkey prefix.Files Modified
Modified:
.github/ISSUE_TEMPLATE/config.yml,.github/pull_request_template.mdBRAND.md,CONTRIBUTING.md,DESIGN.md,PRODUCT.md,README.md,RELEASES.mdcontent/_intro.md,content/about.md,content/badge.md,content/check.md,content/contribute.md,content/install.md,content/methodology.md,content/scorecard-schema.mddocker/sandbox/README.md,docker/score/README.mddocs/runbooks/live-scoring-analytics.md,docs/runbooks/live-scoring-monitoring.mdscripts/SYNCS.md,scripts/generate-pack-readme.mjs,scripts/smoke-api-score.shstyles/brand/{FillerAdjectives,HedgeWords,MarketingRegister}.yml,styles/brand/README.mdstyles/site/{BannedAesthetics,BannedFonts}.yml,styles/site/README.mdstyles/config/vocabularies/site/accept.txt(addedCrowdsourced)tests/wrangler-config.test.tsCreated:
.github/ISSUE_TEMPLATE/00-blank.ymlRenamed:
ARCHITECTURE.mdtoRELEASES-RATIONALE.md(91% similarity; same content with prose-pass edits applied)Deleted:
Key Features
.github/ISSUE_TEMPLATE/config.yml. Tier-3 includes a new tool-registry intake on the linter side and a skill-bundle intake on the skill side.Benefits
/installor/checkno longer believe two binaries ship when one does, and the page title names the binary they'll actually invoke.README.md,content/*.md,BRAND.md,PRODUCT.md,DESIGN.md) drops to clean unslop scores while preserving em-dashes that carry real emphasis or contrast.Breaking Changes
ARCHITECTURE.mdis renamed but no public anchor was published; the file was already a contributor-facing rationale doc. Internal cross-references in this repo are updated. External links toARCHITECTURE.md(if any) would 404.Deployment Notes
No build artifact changes. The
docs-only deploy filterinpaths-ignorealready covers root*.mdchanges so wrangler will produce a bit-identical Worker.Screenshots/Recordings
n/a (no rendered-output changes).
Checklist
Additional Context
The four-commit shape on this branch will land as a single squash commit on
dev; the PR title above is what survives.Cross-repo audit finding (not fixed in this PR): the same
DEFAULT_PACKSvendor-leftover bug exists inagentnative-cli/scripts/generate-pack-readme.mjs(should be["brand"]there; onlybrandis a custom pack in that repo).agentnative-skillhas nostyles/dir, so it is not affected.