Skip to content

docs(core): split the shared-account platform guide out of the README; document create() and defaults - #1635

Draft
xyos wants to merge 6 commits into
aws:mainfrom
xyos:docs/readme-core
Draft

xyos wants to merge 6 commits into
aws:mainfrom
xyos:docs/readme-core

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

packages/core/README.md was 1,886 lines and 18,737 words, with 93 prose lines over 400 characters, and npm run docs core prints all of it.

  • More than half of it (983 lines) was the platform team's side of running many apps in one AWS account: three IAM policies in full, the pipeline, the project template and an adoption procedure.
  • Several statements were wrong: that every allowedOrigins entry is a regex and an invalid one falls back to a literal match, that only the backend and amplify templates serve the API on :3001, that -32602 is reserved, and that a null params gives no arguments.
  • BlocksStack.create() and the defaults.* options were used in every example and documented nowhere in the file.
  • Rules sat in single paragraphs of 700 to 3,000 characters, and the RPC path rules were stated in two sections.

Issue #, if available:

Changes

Four commits, in this order.

1. bd027bf9d Production allowedOrigins rules (README). A plain origin is matched exactly and an invalid entry fails synth (packages/core/src/cors.ts:343-383). The Pipeline pointer links to the pipeline README.

2. c024d9d0b Move of the platform guide. 983 lines move verbatim from the README into the new packages/core/SHARED-ACCOUNT.md; only the six heading levels change. The README section keeps what each app sets and links to the file. Also in this commit:

  • packages/core/package.json: SHARED-ACCOUNT.md added to files.
  • packages/core/src/cdk/readme-policies.test.ts: the test that parses every JSON policy block and checks each full policy against IAM's managed-policy limit of 6,144 characters now reads SHARED-ACCOUNT.md instead of a slice of the README.
  • JSDoc in packages/core/src/cdk/blocks-defaults.ts (permissionsBoundary, appIdentity) and comments in app-isolation-rules.ts and test-apps/comprehensive/test/app-identity-synth.test.ts name the file instead of the README section.

3. packages/core/README.md. Corrections:

  • Port: blocks.dev.port sets it; 3000 by default (packages/core/src/scripts/dev-server.ts:1036), 3001 in api-only, backend, cron, observability, sql (packages/create-blocks-app/templates/*/package.json) and the amplify overlay (packages/create-blocks-app/src/index.ts:952).
  • -32602 is returned when params is present and is neither an array nor an object, null included (packages/core/src/rpc.ts:248-258, rpc.test.ts:422-441). -32603 is not used (rpc.ts:87 is its only occurrence).
  • "Shared API gateway" said the gateway's RPC URL is the ApiUrl output; ApiUrl is publicApiUrl (packages/core/src/cdk/index.ts:173-192).
  • The IAM report field is condition, not conditions (packages/core/src/cdk/iam-report.ts:16-24).
  • Both RPC paths are stated once, under "Calling the API over HTTP" (blocks-defaults.ts:319-347, rpc.ts:239-246).

Added, each derived from the source: a table of entry points (package.json exports); ## BlocksStack and BlocksBackend with create() props (src/common/index.ts:623-700), result properties (src/cdk/index.ts:108-192) and all 13 defaults.* options with both preset values (src/cdk/blocks-defaults.ts:41-487); signatures and option tables for Scope, ApiNamespace, isBlocksError and withAuth; an apiWaf subsection (src/cdk/api-waf.ts:31-77).

Structure: the ## Key Exports wrapper is removed and each export is a ## section; withAuth moves to after RawRoute. Long rule paragraphs are lists; the IAM report's violations are a table.

Removed: the per-door settings matrix, build retention and plain-HTTP details under Hosting (in packages/hosting/README.md, linked); curl examples (in npm run docs troubleshooting); the partial list of Building Block packages (npm run docs); a sentence about a future release; design rationale.

4. packages/core/SHARED-ACCOUNT.md. One correction: the per-service table said AWS::BedrockAgentCore::Runtime is "not scoped"; the text below it and the boundary's OwnTaggedResources statement scope it by tag. The row and the adoption list of tag-scoped types now say so. Otherwise wording only: long paragraphs become lists, acronym glosses and repeated statements are removed. No JSON policy block, shell command or heading changes.

A further commit regenerates the block catalog in packages/blocks/README.md (npm run sync-docs): the first sentence of the core README changed from "with the AWS Blocks" to "with AWS Blocks", and the catalog row copies it.

File Lines Words Prose lines over 400 characters
packages/core/README.md 1,886 → 985 18,737 → 11,807 93 → 28
packages/core/SHARED-ACCOUNT.md (new) 0 → 1,042 0 → 6,100 0 → 24
Total 1,886 → 2,027 18,737 → 17,907 93 → 52

The two files together are about as long as the README was. What changes is what npm run docs core prints: 11,807 words instead of 18,737.

Look hardest at:

  • The move and the JSDoc that now names SHARED-ACCOUNT.md: a public doc comment changed.
  • The defaults.* table and both preset columns against packages/core/src/cdk/blocks-defaults.ts.
  • The removal of ## Key Exports: the heading outline changes, and with it what npm run docs core -- --section <topic> matches.
  • The port and JSON-RPC params statements.

Not changed on purpose:

  • Import specifiers: BlocksStack, BlocksBackend and BlocksPresets are shown from @aws-blocks/blocks/cdk and Hosting from @aws-blocks/core/cdk, as before.
  • JSDoc in packages/core/src/common/index.ts still says a future release will reject a fullId collision.
  • Runtime config, WAF, request checks and service-principal trust stay in the README.

Open questions:

  • Does the defaults.* table belong here or in the @aws-blocks/blocks guide?
  • BLOCKS_SKIP_FRONTEND_BUILD, HostingPresets and npm run sandbox:preview are documented only in the core README, not in the hosting README. Which is their home?
  • packages/blocks/TROUBLESHOOTING.md says every namespace is served at POST /aws-blocks/api; under apiFrontDoor: 'cloudfront' and strictNamespacePlacement that is not the whole rule.
  • SHARED-ACCOUNT.md has no execution-policy JSON for AgentCore runtimes, only prose; the "tag" row was checked against that prose and the boundary JSON.
  • SHARED-ACCOUNT.md still says Lambda VpcConfig and RDS subnet groups "very likely have the same gap (not yet verified)". Someone who can test it should state it either way.

Carried from main: the directory rename to .cdk-blocks-sandbox (#1644) is applied to the revised text: nine lines of packages/core/README.md, including the heading "Runtime config (/.cdk-blocks-sandbox/config.json)".

Related pull requests: supersedes the core part of #1496 (the CORS correction and the Pipeline pointer, taken over unchanged as bd027bf9d). Open pull requests that also touch packages/core/README.md: #726, #1197, #1402, #1405, #1615. Whichever merges second rebases.

Part of a set of README revisions: #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), #1643 (contributor docs). Each merges on its own.

Validation

Run on this branch alone at 030a62658, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in 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 main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and the sandbox e2e suites. CI runs them.

Files other than Markdown in this pull request: packages/core/package.json, packages/core/src/cdk/app-isolation-rules.ts, packages/core/src/cdk/blocks-defaults.ts, packages/core/src/cdk/readme-policies.test.ts, test-apps/comprehensive/test/app-identity-synth.test.ts.

Tests changed: packages/core/src/cdk/readme-policies.test.ts, test-apps/comprehensive/test/app-identity-synth.test.ts. No test was added: the tests listed above already read these files.

Checklist

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 2d05db1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@aws-blocks/core Patch
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch

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

xyos added 6 commits November 19, 2026 05:47
The production CORS subsection said every allowedOrigins entry is a regex, that an invalid regex falls back to a literal match, and that https://app.example.com also matches https://appXexample.com.
A plain origin is matched exactly and an invalid entry fails synth (src/cors.ts); the subsection now says so and links to the allowedOrigins rules above it.
The Pipeline pointer links to the pipeline README.
…T.md

More than half of the core README (983 of 1,884 lines) was the platform's side of running many apps in one AWS account: three IAM policies in full, the pipeline, the project template and adopting defaults.appIdentity in an existing app.
That text moves verbatim into SHARED-ACCOUNT.md, added to the package's files; only its heading levels change.
The README section keeps what each app sets (defaults.appIdentity, defaults.permissionsBoundary, the reserved ids, the IAM report) and links to the file.
readme-policies.test.ts reads the JSON policies from the new file; JSDoc and comments that named the README section for the policies name the file.
…orrect port and params rules

The README said only the backend and amplify templates serve the API on :3001, that -32602 is reserved, that a null params gives no arguments, that the shared gateway's RPC URL is the ApiUrl stack output, and that IAM report statements have a conditions field.
It now says blocks.dev.port sets the port (3001 in the five templates without a frontend and in the amplify overlay), that params which is present and is neither an array nor an object, null included, fails with -32602 (src/rpc.ts), that ApiUrl is publicApiUrl (src/cdk/index.ts), and that the field is condition (src/cdk/iam-report.ts).
A new section, BlocksStack and BlocksBackend, documents create(), its props, the properties of the result and every defaults option with its value in both presets (src/cdk/blocks-defaults.ts); the file opens with a table of entry points, and Scope, ApiNamespace and withAuth open with their signatures.
The Key Exports wrapper is removed, so each export is its own level-two section, and withAuth moves next to the other exports.
The two RPC paths are stated once under Calling the API over HTTP, and rules that were single paragraphs (resend, runtime config, WAF, request checks, allowedOrigins, service-principal trust, the IAM report's violations) are lists or tables.
The per-door settings matrix, build retention and plain-HTTP details under Hosting are replaced by a link to the hosting README, which holds them.
…d; long rules become lists

The per-service table said AWS::BedrockAgentCore::Runtime is not scoped, while the text below it and the boundary's OwnTaggedResources statement scope runtimes by the app tag.
The row now says tag, with the runtimes' workload identities as an accepted exception, and the adoption section's list of tag-scoped types includes AgentCore runtimes.
The boundary's statement groups, the five tag statements, the API Gateway tagging rules, the AgentCore rules, the bootstrap-template steps, the pipeline's two commands and adoption step 4 are lists instead of single paragraphs.
Acronym glosses and repeated statements are removed; the Limits item still says runtime API calls are outside the isolation.
No JSON policy block, shell command or heading changes.
The first sentence of the core README changed ("with the AWS Blocks" became "with AWS Blocks"); `npm run sync-docs` copies it into the catalog table.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant