Repository navigation
Conversation
🦋 Changeset detectedLatest commit: 8eca810 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-contributor-docs
branch
3 times, most recently
from
November 19, 2026 06:11
1568eed to
0aebdb3
Compare
…design docs to the index The root README listed 11 of the 14 `create-blocks-app` templates and omitted `Compute` from the Blocks table; it now points to `npx @aws-blocks/create-blocks-app --help`, which lists every template, and the table lists `Compute`. The repository layout named the root `blocks/` and omitted three directories; it now shows `aws-blocks/` with `test-infra/`, `tasks/` and `docs/`. The Contributing section links `CONTRIBUTING.md` and `AGENTS.md`. Statements made twice (no AWS account needed, no code changes, the definition of a Block, the Node.js requirement, the Developer Guide link) are made once. `docs/README.md` adds `design/compute-selection-api.md` and `design/scaffold-new-bb.md` to the Design list and drops bold from its links.
…b` paths; add a config table The README placed the task matrix in `pr-agent-bench.yml` and said it covers 16 Building Blocks; the matrix is the `include:` list of the `bench` job in `agent-bench.yml` and names 14. It wrote helper paths as `lib/...`; the files are in `steps/lib/`. A "Run it" section now follows the introduction: the two workflows, the automatic triggers and their path filter, the manual dispatch command, the harness test command and the local single-step example. A "Configuration" table lists each variable, where it is set and its default. Indicators and noise bands are tables, the scoring topics are `###` headings, and the file table adds six files it omitted. Sentences about designs the bench does not use (microVM, label gate) are removed.
…val its own section The dispatch command sat unlabelled under "Repository setup"; it is now in a "Run the check" section after the introduction, with the `trials` range (1 to 50, default 1) and the fact that a new dispatch for the same pull request cancels the running one. "Approving a run" is its own section, as a list. The cost metrics, the session invariants and the calibration outputs are lists. Two one-off measurements and the sentence about a planned cross-version replay are removed, and security facts already stated in "Private traces", "Package provenance" and "Accounting" are not repeated under "Security boundaries".
…e shapes and CI credentials
`test-infra/README.md` said the VPC quota is 5 per Region while its own account setup steps request 20; it now says 5 is the default and 20 is what the E2E pool accounts request.
`test-apps/native-bindings/README.md` described the upload handle as `{ url, fields }` for a multipart upload; it is `{ __blocks: 'file-bucket/upload', url, contentType }`, sent with `PUT`, and the download handle carries the `__blocks` tag too.
`test-apps/telemetry/README.md` said CI provides credentials through `aws-actions/configure-aws-credentials`; the job uses the repository's `e2e-aws-credentials` action, and the sentence is removed.
`tasks/README.md` no longer says every spec declares the same three helpers.
`test-infra/README.md` has one title with two sections, the `blocks-github-e2e` permissions as a list and the bench follow-up as numbered steps; `test-apps/telemetry/README.md` starts with "Running".
The README documented an API that no package exports: `SQLTable`, `LLM`, `getValue`, `enqueue`, string scopes such as `'app'`.
`packages/foundations/src/index.ts` is `export default {}` and `package.json` sets `"private": true`.
The README now says so, points to `@aws-blocks/blocks` and the `packages/bb-*` READMEs for the Building Blocks that ship, and keeps one snippet.
The two-`Auth`-block snippet is unchanged because `packages/bb-auth/src/multi-block-snippets.test.ts` compiles and counts it.
… run dashboard` The README said `npm run dashboard` in an app starts the dashboard; no `create-blocks-app` template defines that script. It now names `dashboard()` from `@aws-blocks/core/scripts`. The install offer states its conditions (interactive terminal, `npm install --save-dev`) and the port is given as the first free port from 4400, or `--port <n>`. The line about a future provider is removed.
xyos
force-pushed
the
docs/readme-contributor-docs
branch
from
November 19, 2026 14:23
0aebdb3 to
4625767
Compare
This branch has not been deployed
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
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.
Problem
Ten READMEs that contributors and maintainers read (1,653 lines, 13,773 words) contained statements the source contradicts, and their run commands sat far from the top.
packages/foundations/README.mddocumented 197 lines of API (SQLTable,LLM,getValue,enqueue) for a package whosesrc/index.tsisexport default {}.packages/admin-ui/README.mdsaidnpm run dashboardstarts the dashboard; no template defines that script.test-apps/native-bindings/README.mddescribed the upload handle as{ url, fields }for a multipart upload; the code returns a tagged handle and uploads withPUT.scripts/agent-bench/README.mdplaced the task matrix in the wrong workflow file, counted 16 Building Blocks where the matrix names 14, and gave its local run example at the end of a 490-line file.Issue #, if available:
Changes
README.md. Listed 11 of 14 templates; now points tonpx @aws-blocks/create-blocks-app --help(14 directories inpackages/create-blocks-app/templates/). The Blocks table listsCompute. The layout root isaws-blocks/, notblocks/, and addstest-infra/,tasks/,docs/. Contributing linksCONTRIBUTING.mdandAGENTS.md.docs/README.md. The Design list addsdesign/compute-selection-api.mdanddesign/scaffold-new-bb.md.scripts/agent-bench/README.md.include:list of thebenchjob inagent-bench.yml(.github/workflows/agent-bench.yml:90-101), not inpr-agent-bench.yml; it names 14 Building Blocks, not 16.lib/...paths readsteps/lib/...;scripts/agent-bench/has nolib/..github/workflows/pr-agent-bench.yml:38-54).npm run test:ci -w scripts/agent-bench, the local example moved from the end) and a "Configuration" table derived fromagent-bench.yml,steps/2-agent-run.ts,steps/4-judge.tsandsteps/lib/isolation.mjs.###headings; the file table adds six files it omitted.scripts/harbor-bench/README.md. The dispatch command moves from "Repository setup" to a new "Run the check" section, with thetrialsrange and same-PR cancellation (.github/workflows/harbor-agent-check.yml:10-21). "Approving a run" is its own section. Two one-off measurements and the planned cross-version replay sentence are removed.test-infra/README.md. Said "VPC quota is 5 per region" while step 4 of "More E2E accounts" requests 20; now 5 by default, 20 requested (test-infra/vpc-test-stack.ts:7for the default). One title with two sections instead of two level-1 headings. Theblocks-github-e2epermissions are a list and the bench follow-up is five numbered steps.tasks/README.md. "Every spec re-declares the same small helpers" became "A spec declares the helpers it needs" (tasks/observability-api/test.spec.tshas norpcwrapper).test-apps/native-bindings/README.md. Upload:fileCreateUploadHandle(path, contentType?)(test-apps/native-bindings/aws-blocks/index.ts:585) returns{ __blocks: 'file-bucket/upload', url, contentType }, uploaded withPUT(packages/bb-file-bucket/src/index.aws.ts:221-231). Download:{ __blocks: 'file-bucket/download', url }(index.aws.ts:217). "Sandbox/Production" became "Deployed sandbox" (package.json:22-24:deployisdeploy:sandbox). Sign-up codes, OIDC, the second federated block (auth-sso) and the bearer-token note are lists; general stub IdP rules point to theAuthREADME. "All four auth blocks areAuth" is removed; the table has the fourAuthrows.test-apps/telemetry/README.md. "Running" is the first section. The sentence namingaws-actions/configure-aws-credentialsis removed; the job uses./.github/actions/e2e-aws-credentials(.github/workflows/pr-checks.yml:1426).packages/foundations/README.md. Now states the package is private and exports nothing, points to@aws-blocks/blocksand thepackages/bb-*READMEs, and keeps the two-Auth-block snippet unchanged.packages/admin-ui/README.md. Entry point isdashboard()(packages/core/src/scripts/dashboard.ts:364, exported through./scriptsatpackages/core/package.json:67). Install offer:dashboard.ts:259-272. Port:dashboard.ts:17,33.README.mddocs/README.mdpackages/admin-ui/README.mdpackages/foundations/README.mdscripts/agent-bench/README.mdscripts/harbor-bench/README.mdtasks/README.mdtest-apps/native-bindings/README.mdtest-apps/telemetry/README.mdtest-infra/README.mdThe two bench READMEs gain lines because paragraphs became lists and tables.
Look hardest at:
packages/foundations/README.md, 197 → 40 lines. A maintainer must confirm that the removed API was never shipped under these names. The kept snippet is unchanged becausepackages/bb-auth/src/multi-block-snippets.test.tsreads this README, compiles the snippet and expects three such snippets underpackages/.test-infra(VPC quota),test-apps/native-bindings(handle shapes, "Deployed sandbox") andscripts/agent-bench(matrix location, 14 Building Blocks, the "Configuration" table defaults).Not changed on purpose:
.changeset/README.md(stock text of the changesets tool). The root README's opening paragraph, which stays one paragraph over 400 characters..github/workflows/agent-bench.yml:89, whose comment still says "10 cells cover 16 Blocks".Open questions:
foundations: keep the package with this README, or remove it? Removal also changes the file list and the count of 3 inmulti-block-snippets.test.ts.npm run dashboard(packages/admin-ui/app/page.tsx:300,app/playground/page.tsx:247,app/deployments/[id]/page.tsx:195,src/components/inventory-nav.tsx:194), andpackages/admin-ui/src/lib/commands.ts:36says thedefaulttemplate defines it. No template'spackage.jsonhas adashboardscript. Should a template define it, or should those strings change?test-infra: the README says pool accounts request a VPC quota of 20; whether each increase was granted is not visible in the repository.scripts/agent-bench:BLOCKS_TELEMETRY_CANARY_IDis called a "workflow secret"; repository or environment secret?steps/finalize-result.mjsalso stampsstatus: cancelled, which the failure-handling paragraph does not list.Carried from
main: two changes merged after this pull request was opened are applied to the revised text. The directory rename to.cdk-blocks-sandbox(#1644): one line each inscripts/agent-bench/README.mdandtest-apps/telemetry/README.md. The repo slugaws/cdk-blocks(#1647): the dispatch command inscripts/harbor-bench/README.md, and intest-infra/README.mdthenpm testparagraph and the new paragraph on renaming or moving the repo.Related pull requests: supersedes none. Open pull requests that touch the same files:
README.md: feat(bb-sms-client): add SmsClient building block for SMS and mobile push #49, feat(observability): add OpenTelemetry building blocks (OtelMetrics / OtelLogger / OtelTracer) #50, feat(bb-event-bus): add EventBridge-backed pub/sub event bus block #64, refactor!: rename the scaffolded backend folder to cdk-blocks #1630scripts/agent-bench/README.md: fix(bench): harness trace/classification integrity + failure-analysis honesty #217, docs(bench): add pr-agent-bench skill (how-to-read runbook) #218, ci(agent-bench): keep a valid latest-main baseline, skip cancelled summaries, allow InvokeModel #1347, feat(core)!: follow CDK's telemetry opt-out and remove the AWS Blocks one #1606test-apps/telemetry/README.md: test(telemetry): assert the send, not a 500 ms answer, in command cases #1331, feat(core)!: follow CDK's telemetry opt-out and remove the AWS Blocks one #1606test-apps/native-bindings/README.md: test(native-dart): e2e for two federated Auth blocks #1482test-infra/README.md: ci(compute-smoke): share the compute test VPC through permanent endpoints #961packages/admin-ui/README.md: feat(core, blocks, hosting, create-blocks-app, admin-ui, bb-database)!: rename the hidden .blocks folder to .cdk-blocks and consolidate local data under it #1607Whichever merges second rebases.
Part of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs). Each merges on its own.
Validation
Run on this branch alone at
0aebdb3ba, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.