From 02c3af99944fbec4f859d2989ecb65be33f9468f Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 21 May 2026 13:05:01 -0500 Subject: [PATCH 1/3] docs(readme): rewrite to reflect current dev surface The previous README claimed the site was "static HTML + CSS, no build step" and described scorecards plus a live-scoring form at incorrect routes. None of that has been accurate since the build pipeline, Cloudflare Worker, scorecard renderer, live-scoring loop, and skill bundle endpoint landed. The rewrite replaces the four stale sections with: a what-it-serves route table, a stack summary (Worker over Static Assets, build pipeline, DO + R2 + KV + Turnstile for live scoring), a local-development recipe matching package.json scripts, the full seven-stage pre-push hook list, the branch plus release model pointing at RELEASES.md, a documentation map covering AGENTS / CONTRIBUTING / DESIGN / BRAND / PRODUCT / RELEASES / docs/runbooks, a related-repositories list, and a Contributing section mirroring the anc CLI README (three-tier shape, local setup recipe, cross-repo routing). Verified: bash scripts/prose-check.sh reports 0 blocking; unslop scores 0 (clean) after the route list was restructured from em-dashed bullets into a real table. --- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 94 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 32de499..d065430 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,108 @@ # agentnative-site -Source for the agent-native CLI standard website. Presents the 7 principles for building CLI tools that AI agents can -operate as first-class users. The site also hosts curated tool scorecards at `/score/` and a live-scoring form at -`/score` that returns shareable results at `/score/live/`. +Source for [anc.dev](https://anc.dev), the public surface for the agent-native CLI standard. The site publishes the +seven principles of the standard, the ANC 100 leaderboard, per-tool curated scorecards, a live-scoring form, the score +badge surface, and the agent-native-cli skill bundle distribution endpoint. -## Development +## What it serves -Static HTML + CSS. No build step. Open `index.html` in a browser. +| Route | Purpose | +| ------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `/` | Homepage with the principle index and a live-score form to `/api/score` | +| `/scorecards` | The ANC 100 leaderboard (every curated tool, sortable) | +| `/score/` | Per-tool curated scorecards (renders from `scorecards/.json`) | +| `/score/live/` | Shareable live-score result pages backed by the R2 score cache | +| `/check`, `/install`, `/methodology`, `/badge`, `/scorecard-schema` | Supporting pages on usage, install, scoring methodology, badge, schema | +| `/contribute`, `/about` | Contribution map and attribution | +| `/skill` | Human-facing install for the `agent-native-cli` skill bundle | +| `/skill.json` | Canonical machine-primary skill manifest | +| `/llms.txt`, `/llms-full.txt` | llmstxt.org convention (summary index plus full concatenated spec) | -After cloning, point git at the repo's hook directory once: +Every HTML page has a markdown twin reachable via `.md` suffix or `Accept: text/markdown` content negotiation. + +## Stack + +Cloudflare Worker over Static Assets. Build pipeline renders markdown in `content/` to HTML at `dist/` via `bun +src/build/build.mjs`. Live scoring runs in a Cloudflare Sandbox Durable Object, cached in R2, rate-limited by KV, and +gated by Turnstile. Full inventory in [`wrangler.jsonc`](./wrangler.jsonc); design contract in +[`DESIGN.md`](./DESIGN.md). + +## Local development + +```bash +bun install +bun run build # produces dist/ +bun run dev # bun run build && wrangler dev --local +wrangler dev --env staging # local Worker against staging bindings +bun test # unit + regression +bun run test:e2e # Playwright +``` + +After cloning, point git at the repo's hooks once: ```bash git config core.hooksPath scripts/hooks ``` -This enables `scripts/hooks/pre-push`, which runs `bun run lint`, `bun run build`, `bun test`, and `wrangler deploy ---dry-run` before every push: the same gates CI enforces. Bypass intentionally with `git push --no-verify` if you really -need to (rare; the hook exists to catch what we've lost time to before). +This enables `scripts/hooks/pre-push`, which runs the seven local gates before every push: `lint`, `build`, `tests`, +`wrangler deploy --dry-run`, pack-README drift, banned-fonts scan, and `scripts/prose-check.sh` (Vale plus LanguageTool +when reachable). CI enforces stages 1 through 4; stages 5 through 7 are pre-push only. + +## Branch and release model + +Feature branches PR to `dev`. Production cuts via `release/-` cherry-picked from `dev` to `main`. +`deploy.yml` ships `main` to `anc.dev` on push. The full procedure lives in [`RELEASES.md`](./RELEASES.md); rationale in +[`RELEASES-RATIONALE.md`](./RELEASES-RATIONALE.md). + +## Documentation map -## Deployment +| File | Purpose | +| ----------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| [`AGENTS.md`](./AGENTS.md) | Agent-facing project brief: scope, voice, structure, surfaces | +| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Contribution tiers, dev setup, pre-push hook, PR conventions | +| [`DESIGN.md`](./DESIGN.md) | Visual and structural design contract | +| [`BRAND.md`](./BRAND.md) | Voice, positioning, naming | +| [`PRODUCT.md`](./PRODUCT.md) | Product framing and roadmap context | +| [`RELEASES.md`](./RELEASES.md) / [`RELEASES-RATIONALE.md`](./RELEASES-RATIONALE.md) | Release runbook plus its reasoning | +| [`docs/runbooks/`](./docs/runbooks/) | Operational runbook set (live-scoring, analytics, deploy) | + +## Related repositories + +- [agentnative](https://github.com/brettdavies/agentnative): the canonical spec (principle text, pressure-tests, + versioning policy) +- [agentnative-cli](https://github.com/brettdavies/agentnative-cli): `anc`, the CLI linter and scoring engine, plus the + tool registry +- [agentnative-skill](https://github.com/brettdavies/agentnative-skill): the `agent-native-cli` skill bundle, installed + via [anc.dev/skill](https://anc.dev/skill) + +## Contributing + +Three shapes of contribution, in order of cost: + +1. **Signal** (site bug, rendering issue, broken link, copy critique, mobile-layout or performance regression): file an + issue with the matching template at + [github.com/brettdavies/agentnative-site/issues/new/choose](https://github.com/brettdavies/agentnative-site/issues/new/choose). +2. **Proposal** (new page or section, scorecard renderer rework, Worker route addition, build-pipeline change, + live-scoring surface change): open a design issue first; the maintainer signs off before code lands. +3. **Code**: PR against `dev` (per branch discipline). + +Local setup: + +```bash +git clone https://github.com/brettdavies/agentnative-site +cd agentnative-site +git config core.hooksPath scripts/hooks # mirror CI locally on every push +bun install +bun run build +bun test +``` -Cloudflare Workers. Pushes to `main` deploy automatically. +The full tier breakdown, pre-push hook contents, and PR conventions live in [`CONTRIBUTING.md`](./CONTRIBUTING.md). +Cross-repo routing: principle-level discussion (MUST/SHOULD/MAY tier changes, new principles, applicability clauses) +goes to the [spec repo](https://github.com/brettdavies/agentnative/issues/new/choose); scoring-engine and registry work +to [agentnative-cli](https://github.com/brettdavies/agentnative-cli/issues/new/choose); skill bundle changes to +[agentnative-skill](https://github.com/brettdavies/agentnative-skill/issues/new/choose). -## Related +## License -- [agentnative-cli](https://github.com/brettdavies/agentnative-cli): the CLI linter that checks compliance with this - standard -- [agentnative-skill](https://github.com/brettdavies/agentnative-skill): the agent-native-cli skill bundle (SKILL.md + - checklists + scripts) installed via [anc.dev/skill](https://anc.dev/skill) +See [`LICENSE`](./LICENSE). From 5c1239b2e0bf0814291ca0a6801897390fc26530 Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 21 May 2026 13:12:28 -0500 Subject: [PATCH 2/3] fix(readme): eight principles, not seven Stale carry-over from the v0 spec which had seven principles. The site copy in content/_intro.md ("Eight principles, each expressing a requirement", "/p1 through /p8") and the agentnative-cli README ("## The 8 Principles") both reflect eight; only the freshly-rewritten README on this branch still said seven. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d065430..dbdc891 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # agentnative-site Source for [anc.dev](https://anc.dev), the public surface for the agent-native CLI standard. The site publishes the -seven principles of the standard, the ANC 100 leaderboard, per-tool curated scorecards, a live-scoring form, the score +eight principles of the standard, the ANC 100 leaderboard, per-tool curated scorecards, a live-scoring form, the score badge surface, and the agent-native-cli skill bundle distribution endpoint. ## What it serves From e0cf92e32d01abeb3152dd8eb9f4dfea5288c2c7 Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 21 May 2026 14:20:14 -0500 Subject: [PATCH 3/3] docs(readme): add Scoring section reflecting agentnative-cli v0.4.0 The v0.4.0 CLI README documents the scoring formula (pass / (pass + warn + fail), skips and errors excluded), the MUST/SHOULD/ MAY tier mapping to fail/warn statuses, and the 80% badge eligibility floor. None of that surfaced in the site README even though the site is the public scoring display. Add a tight Scoring section between What it serves and Stack: formula one-liner, tier mapping, badge floor, and pointers to the three pages that hold the full detail (/methodology, /scorecard-schema, /badge), plus a pointer to the scoring engine repo. The site README stays scoped to the site; depth lives on the content pages. --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index dbdc891..72bd7f9 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,15 @@ badge surface, and the agent-native-cli skill bundle distribution endpoint. Every HTML page has a markdown twin reachable via `.md` suffix or `Accept: text/markdown` content negotiation. +## Scoring + +Per-tool scorecards display a percent computed as `pass / (pass + warn + fail)` (skips and errors are excluded so +inapplicable checks do not drag the score). MUST-tier misses count as `fail`; SHOULD- or MAY-tier misses count as +`warn`. Badge eligibility starts at 80%. Full formula and tier mapping at [`/methodology`](https://anc.dev/methodology); +per-field JSON schema at [`/scorecard-schema`](https://anc.dev/scorecard-schema); badge contract at +[`/badge`](https://anc.dev/badge). The scoring engine itself lives in +[`agentnative-cli`](https://github.com/brettdavies/agentnative-cli). + ## Stack Cloudflare Worker over Static Assets. Build pipeline renders markdown in `content/` to HTML at `dist/` via `bun