Light, fluffy, and always free - The AWS Local Emulator alternative
docs: fix stale image tags, release model, service nav and contributor checklists (#2980)
Hector Venturaeb0472fccc1a
diff --git a/.github/workflows/docs-actions.yml b/.github/workflows/docs-actions.ymlindex b539d9972f..ffa4624295 100644--- a/.github/workflows/docs-actions.yml+++ b/.github/workflows/docs-actions.yml@@ -11,7 +11,8 @@ on:paths:- 'src/main/**'- 'src/test/resources/cloudformation/**'- - 'docs/services/**'+ - 'docs/**'+ - 'mkdocs.yml'- 'tools/docs/**'- 'Makefile'- '.github/workflows/docs-actions.yml'@@ -21,7 +22,8 @@ on:paths:- 'src/main/**'- 'src/test/resources/cloudformation/**'- - 'docs/services/**'+ - 'docs/**'+ - 'mkdocs.yml'- 'tools/docs/**'- 'Makefile'- '.github/workflows/docs-actions.yml'@@ -35,7 +37,7 @@ concurrency:jobs:action-tables:- name: Action tables in sync+ name: Docs in syncruns-on: ubuntu-latesttimeout-minutes: 5steps:@@ -47,10 +49,13 @@ jobs:python-version: "3.x"- name: Install tooling deps- run: pip install -r tools/docs/requirements.txt+ run: pip install -r tools/docs/requirements.txt -r docs/requirements.txt- name: Run action-table testsrun: make docs-test- name: Check action tables are in syncrun: make docs-check++ - name: Build docs (strict)+ run: mkdocs build --strict --site-dir /tmp/sitediff --git a/AGENTS.md b/AGENTS.mdindex 8ed8d1552f..a20f37653b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -249,17 +249,22 @@ When adding functionality:## Adding a New AWS Service-1. Create a package under `services/`-2. Add:- - Controller- - Service- - `model/`-3. Register the service in `ServiceRegistry`-4. Add config to `EmulatorConfig`-5. Add YAML config in main and test config files-6. Wire storage through `StorageFactory`-7. Add tests-8. Update documentation+1. Create a package under `services/<svc>/` with a Controller, a Service, and `model/`+2. Add a `<Svc>ServiceConfig` interface and its accessor on `ServicesConfig` in `EmulatorConfig`+3. Add one `descriptor(...)` entry in `ResolvedServiceCatalog`. This is the registration point;+ `ServiceRegistry` only reads the catalog and has no registration API+4. Add `floci.services.<key>.enabled` to both `src/main/resources/application.yml` and+ `src/test/resources/application.yml`+5. JSON 1.1 only: inject the handler in `AwsJson11Controller`+6. Obtain storage through `StorageFactory` and implement `Resettable`+7. List any static `Random` or `SecureRandom` field under `--initialize-at-run-time` in+ `application.yml`+8. Add `<Svc>ServiceTest` and `<Svc>IntegrationTest`+9. Document it: `docs/services/<svc>.md`, a `mkdocs.yml` nav entry, a Service Matrix row in+ `docs/services/index.md`, and a row in the README category table+10. Register the handler in `tools/docs/services.yaml`, then run `make docs-sync` and+ `make docs-check`+11. Add a `TestFixtures` client factory and a `<Svc>Test` in `compatibility-tests/sdk-test-java`---diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5067931fbe..41ebaabe4b 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -49,12 +49,12 @@ If you prefer to use your own Maven installation (3.9+), you can use `mvn` inste## Branching Model-Floci uses a **tag-driven release model**. Docker images are never published on PR merge, only when a maintainer pushes a version tag.+Floci uses a **tag-driven release model**. Merging a PR never publishes a release image. `main` is published once a day as the `nightly` channel, and a stable release is published only when a maintainer runs the "Release Cut" workflow (`.github/workflows/release-cut.yml`, `workflow_dispatch`). That workflow runs semantic-release, which bumps `pom.xml`, writes `CHANGELOG.md`, commits, and pushes the `X.Y.Z` tag. The tag then triggers `.github/workflows/release.yml`, which builds and publishes the release images to Docker Hub and public ECR.-| Branch | Purpose | Docker published? |+| Branch / tag | Purpose | Docker published? ||---|---|---|-| `main` | Integration branch: all PRs merge here. Treated as unstable/nightly. | No (CI tests only) |-| `X.Y.Z` tag | Signals a production release. Triggers the full Docker publish pipeline. | Yes (`x.y.z`, `latest`, `x.y.z-jvm`, `latest-jvm`) |+| `main` | Integration branch: all PRs merge here. Treated as unstable. | Nightly only (`nightly`, `nightly-<date>`, `nightly-compat`, `nightly-<date>-compat`) via `nightly.yml` |+| `X.Y.Z` tag | Signals a production release. Pushed by the Release Cut workflow. | Yes (`x.y.z`, `latest`, `x.y.z-compat`, `latest-compat`) via `release.yml` |## Commit Message Format@@ -139,12 +139,17 @@ ln -s AGENTS.md COPILOT.md1. Create a package under `src/main/java/.../services/<service>/`2. Add a Controller (follow the correct protocol: Query, JSON 1.1, REST JSON, or REST XML)3. Add a Service (`@ApplicationScoped`) and model POJOs-4. Add config entries in `EmulatorConfig.java` and `application.yml`-5. Register a `ServiceDescriptor` in `ResolvedServiceCatalog`-6. Wire controller/handler dispatch for the service-7. Add integration tests in `*IntegrationTest.java`--`ServiceRegistry`, `ServiceEnabledFilter`, and `StorageFactory` now resolve service metadata from the descriptor catalog. Adding a service should not require new service-keyed switch statements in those consumers.+4. Add a `<Svc>ServiceConfig` interface and its accessor on `ServicesConfig` in `EmulatorConfig.java`+5. Register a `ServiceDescriptor` in `ResolvedServiceCatalog`. This is the only registration point: `ServiceRegistry` reads the catalog and has no registration API+6. Add `floci.services.<key>.enabled` to both `src/main/resources/application.yml` and `src/test/resources/application.yml`+7. Wire controller/handler dispatch for the service (JSON 1.1 handlers are injected into `AwsJson11Controller`)+8. Obtain storage through `StorageFactory` and implement `Resettable`; list any static `Random` or `SecureRandom` field under `--initialize-at-run-time` in `application.yml`+9. Add `*ServiceTest.java` and `*IntegrationTest.java` tests+10. Document it: `docs/services/<service>.md`, a `mkdocs.yml` nav entry, a Service Matrix row in `docs/services/index.md`, and a row in the README category table+11. Register the handler in `tools/docs/services.yaml`, then run `make docs-sync` and `make docs-check`+12. Add a client factory in the compat suite's `TestFixtures` and a `<Svc>Test` under `compatibility-tests/sdk-test-java`++`ServiceRegistry`, `ServiceEnabledFilter`, and `StorageFactory` resolve service metadata from the descriptor catalog. Adding a service should not require new service-keyed switch statements in those consumers. `make docs-check` gates steps 10 and 11: a registered service with no matrix row, a `docs/services` page with no matrix row, and a stale action table all fail CI.Always implement the **real AWS wire protocol**. Never invent custom endpoints. The AWS SDK must work against Floci without modification.@@ -216,7 +221,7 @@ update path.5. Reference any related issues in the PR description.6. Keep at most **5 open PRs** at a time. A bot leaves an advisory note and an `over-pr-limit` label on PRs opened beyond that. Nothing gets closed or blocked, but please land or close your existing PRs before opening more.-Docker images are never built on contributor PRs, so merging to `main` is always cheap.+Docker images are built on contributor PRs only for the compatibility suite (`.github/workflows/compatibility.yml`, on changes under `src/**` and the compat test trees) and are never published, so merging to `main` is always cheap.## Release Process (maintainers)@@ -274,7 +279,7 @@ hand-written and preserved across regeneration, keyed by action name.listed under `deferred_handlers`.- `make docs-test` runs the tooling's unit tests.-Registering a new service is one entry in `tools/docs/services.yaml`.+Registering a new service's action table is one entry in `tools/docs/services.yaml`.## Reporting Security Issuesdiff --git a/Makefile b/Makefileindex c05c3a56f6..238f18aa7d 100644--- a/Makefile+++ b/Makefile@@ -34,7 +34,12 @@ docs-check: ## CI gate: regenerate and fail if anything is stale, unregistered,}@$(PYTHON) tools/docs/check_service_matrix.py --strict || { \echo ""; \- echo "error: a registered service has no row in docs/services/index.md (see warnings above)."; \+ echo "error: the Service Matrix in docs/services/index.md is out of sync (see warnings above)."; \+ exit 1; \+ }+ @! grep -rn -- '-jvm' docs README.md CONTRIBUTING.md || { \+ echo ""; \+ echo "error: docs name a '-jvm' image tag; release.yml publishes only x.y.z, latest and their -compat twins."; \exit 1; \}diff --git a/README.md b/README.mdindex 60d6222ce4..4cf5ead3f2 100644--- a/README.md+++ b/README.md@@ -190,7 +190,7 @@ LocalStack's community edition [sunset in March 2026](https://blog.localstack.cl| CodeBuild | Real Docker execution | No || Native binary | ~40 MB | No |-**85 AWS services. Broad coverage. Free forever.**+**Broad AWS coverage. Free forever.** See the [Services Overview](https://floci.io/floci/services/) for the full list of emulated services.## Architecture Overview@@ -232,13 +232,13 @@ Floci supports local emulation for application services, data services, eventing| Category | Services ||---|---|| Core app services | S3, SQS, SNS, DynamoDB, Lambda, IAM, KMS, Secrets Manager, SSM |-| Events and workflows | EventBridge, EventBridge Pipes, EventBridge Scheduler, Step Functions, SWF, CloudWatch Logs, CloudWatch Metrics |-| API and identity | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Cloud Map |-| Containers and compute | ECS, EC2, Lightsail, EKS, MWAA, ECR, CodeBuild, CodeDeploy, CodePipeline, AWS Batch, Auto Scaling, Application Auto Scaling, Elastic Beanstalk, ELB v2 |-| Data, analytics, and AI | Athena, Glue, EMR, Firehose, Managed Service for Apache Flink, OpenSearch, S3 Tables, S3 Vectors, Textract, Transcribe, Bedrock Runtime, Bedrock AgentCore |+| Events and workflows | EventBridge, EventBridge Pipes, EventBridge Scheduler, Step Functions, SWF, CloudWatch Logs, CloudWatch Metrics, CloudWatch RUM, Managed Prometheus (AMP) |+| API and identity | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Route 53 Resolver, Cloud Map |+| Containers and compute | ECS, EC2, Lightsail, EKS, MWAA, ECR, EFS, CodeBuild, CodeDeploy, CodePipeline, CodeGuru Reviewer, AWS Batch, Auto Scaling, Application Auto Scaling, Elastic Beanstalk, ELB v2, ELB Classic |+| Data, analytics, and AI | Athena, Glue, Lake Formation, EMR, EMR Serverless, Redshift, Firehose, Managed Service for Apache Flink, OpenSearch, S3 Tables, S3 Vectors, Textract, Transcribe, Comprehend, Rekognition, Translate, Bedrock Runtime, Bedrock AgentCore || Databases and caching | RDS, RDS Data API, Neptune, DocumentDB, MemoryDB, ElastiCache |-| Messaging and transfer | SES, Kinesis, MSK, Amazon MQ, Transfer Family, IoT Core |-| Security and governance | AWS Network Firewall, AWS RAM, Service Quotas, WAF v2, CloudTrail, CloudFront, Resource Groups Tagging API, Resource Explorer 2, CloudHSM v2, Organizations |+| Messaging and transfer | SES, Kinesis, MSK, Amazon MQ, Transfer Family, IoT Core, Amazon Connect |+| Security and governance | AWS Network Firewall, AWS RAM, Service Quotas, WAF v2, GuardDuty, CloudTrail, CloudFront, Resource Groups Tagging API, Resource Explorer 2, CloudHSM v2, Organizations, Control Tower, Service Catalog || Cost and billing | Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports || Resilience, backup, and config | AWS FIS, AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation, Cloud Control API |diff --git a/docs/contributing.md b/docs/contributing.mdindex 667d58dbbd..533d77f55a 100644--- a/docs/contributing.md+++ b/docs/contributing.md@@ -90,9 +90,10 @@ Quick summary:1. Create `src/main/java/.../services/<service>/` with a Controller, Service, and `model/` package2. Pick the right protocol (see the protocol table in `AGENTS.md`)-3. Register the service in `ServiceRegistry`-4. Add config in `EmulatorConfig.java` and `application.yml`-5. Add `*IntegrationTest.java` tests+3. Register a `ServiceDescriptor` in `ResolvedServiceCatalog` (`ServiceRegistry` only reads the catalog)+4. Add config in `EmulatorConfig.java` and in both the main and test `application.yml`+5. Add `*ServiceTest.java` and `*IntegrationTest.java` tests+6. Add the docs page, its `mkdocs.yml` nav entry, a Service Matrix row and a README row (`make docs-check` gates the matrix)## Pull Request Checklistdiff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.mdindex a487f12809..c0bf17c394 100644--- a/docs/getting-started/quick-start.md+++ b/docs/getting-started/quick-start.md@@ -29,14 +29,14 @@ This guide gets Floci running and verifies that AWS CLI commands work against itdocker compose up -d```-=== "JVM"+=== "Compat (+ AWS CLI + boto3)"- Use `latest-jvm` if you need broader platform compatibility:+ Use `latest-compat` if you need the AWS CLI and boto3 inside the container:```yamlservices:floci:- image: floci/floci:latest-jvm+ image: floci/floci:latest-compatports:- "4566:4566"volumes:diff --git a/docs/index.md b/docs/index.mdindex beb77c3c70..86e4b5e06e 100644--- a/docs/index.md+++ b/docs/index.md@@ -12,76 +12,7 @@ Floci is a fast, free, and open-source local AWS service emulator built for deve## Supported Services-Floci emulates 85 AWS services. See the [Services Overview](services/index.md) for per-service operation counts, endpoints, and full protocol details.--| Service | Protocol |-|---|---|-| SSM Parameter Store | JSON 1.1 |-| SQS | Query / JSON |-| SNS | Query / JSON |-| SES | Query |-| SES v2 | REST JSON |-| S3 | REST XML |-| DynamoDB + Streams | JSON 1.1 |-| Lambda | REST JSON |-| API Gateway v1 & v2 | REST JSON |-| AppSync | REST JSON |-| Cognito | JSON 1.1 |-| KMS | JSON 1.1 |-| Kinesis | JSON 1.1 |-| Secrets Manager | JSON 1.1 |-| CloudFormation | Query |-| Step Functions | JSON 1.1 |-| IAM | Query |-| STS | Query |-| Organizations | JSON 1.1 |-| ElastiCache (Redis / Valkey) | Query + RESP proxy |-| RDS (PostgreSQL / MySQL) | Query + wire proxy |-| RDS Data API | REST JSON |-| Neptune (graph DB / Gremlin) | Query + WebSocket proxy |-| DocumentDB (MongoDB-compatible) | Query + MongoDB wire |-| MSK (Kafka / Redpanda) | REST JSON + Kafka |-| Amazon MQ (RabbitMQ) | REST JSON + AMQP |-| Athena | JSON 1.1 |-| Glue Data Catalog + Schema Registry | JSON 1.1 |-| Data Firehose | JSON 1.1 |-| Managed Service for Apache Flink | JSON 1.1 |-| ECS | JSON 1.1 |-| EC2 | EC2 Query |-| Lightsail | JSON 1.1 |-| ACM | JSON 1.1 |-| ECR | JSON 1.1 + OCI Distribution |-| Resource Groups Tagging API | JSON 1.1 |-| OpenSearch | REST JSON |-| EventBridge | JSON 1.1 |-| EventBridge Pipes | REST JSON |-| EventBridge Scheduler | REST JSON |-| CloudWatch Logs & Metrics | JSON 1.1 / Query |-| CloudWatch RUM | REST JSON |-| AppConfig + AppConfigData | REST JSON |-| Bedrock Runtime | REST JSON |-| EKS | REST JSON |-| ELB v2 | Query |-| Auto Scaling | Query |-| Elastic Beanstalk | Query |-| CodeBuild | JSON 1.1 |-| CodeDeploy | JSON 1.1 |-| CodePipeline | JSON 1.1 |-| AWS Backup | REST JSON |-| AWS FIS | REST JSON |-| CloudFront | REST XML |-| Route53 | REST XML |-| Cloud Map | JSON 1.1 |-| AWS Config | JSON 1.1 |-| Textract | JSON 1.1 |-| Transcribe | JSON 1.1 |-| Pricing | JSON 1.1 |-| Cost Explorer | JSON 1.1 |-| Cost and Usage Reports | JSON 1.1 |-| BCM Data Exports | JSON 1.1 |-| Transfer Family | JSON 1.1 |-| AWS RAM | REST JSON |-| Service Quotas | JSON 1.1 |+See the [Services Overview](services/index.md) for the full list of emulated services, per-service operation counts, endpoints, and protocol details.## Why Floci?@@ -117,7 +48,7 @@ docker compose up -daws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket```-All 85 AWS services are immediately available at `http://localhost:4566`.+Every emulated service is immediately available at `http://localhost:4566`.[Get started →](getting-started/quick-start.md){ .md-button .md-button--primary }[View services →](services/index.md){ .md-button }diff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.mdindex 8b7cc8b952..9295005c99 100644--- a/docs/services/cloudformation.md+++ b/docs/services/cloudformation.md@@ -48,7 +48,7 @@ Resource types provisioned during `CreateStack` / `UpdateStack` / `DeleteStack`.the backing service and sets a real physical ID plus the `Ref` / `Fn::GetAtt` attributes used bycross-resource references.-> Adding a type? See [Adding a CloudFormation Resource Type](../../CONTRIBUTING.md#adding-a-cloudformation-resource-type).+> Adding a type? See [Adding a CloudFormation Resource Type](https://github.com/floci-io/floci/blob/main/CONTRIBUTING.md#adding-a-cloudformation-resource-type).> Types live in per-service provisioners under `services/cloudformation/provisioners/`. This table> is generated from the provisioner inventory by `make docs-sync`; edit that, not the table.diff --git a/docs/services/index.md b/docs/services/index.mdindex 507a1beab7..f5d882df10 100644--- a/docs/services/index.md+++ b/docs/services/index.md@@ -1,6 +1,6 @@# Services Overview-Floci emulates 85 AWS services on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.+Floci emulates the AWS services listed below on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.This page is the canonical reference for supported service and operation counts. Some services expose separate control-plane and data-plane rows below. Other docs (and the README) should link here rather than duplicating the table.@@ -79,6 +79,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac| [Bedrock AgentCore](bedrock-agentcore.md#data-plane-invokeagentruntime) | `/runtimes/{agentRuntimeArn}/invocations` | REST JSON (binary payload) | 1 (canned-response stub) || [EKS](eks.md) | `/clusters`, `/clusters/{name}`, `/tags/{resourceArn}` | REST JSON | 7 || [ELB v2](elb.md) | `POST /` with `Action=` param | Query | 34 |+| [ELB Classic (v1)](elb-classic.md) | `POST /` with `Action=` and `Version=2012-06-01` | Query | 20 || [WAF v2](wafv2.md) | `POST /` + `X-Amz-Target: AWSWAF_20190729.*` | JSON 1.1 | 35 || [Auto Scaling](autoscaling.md) | `POST /` with `Action=` param | Query | 33 || [Application Auto Scaling](applicationautoscaling.md) | `POST /` + `X-Amz-Target: AnyScaleFrontendService.*` | JSON 1.1 | 9 |diff --git a/mkdocs.yml b/mkdocs.ymlindex e526975639..31d5e30c49 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -36,6 +36,23 @@ theme:- content.code.annotate- content.tabs.link+# Fail the build on any warning so a docs page without a nav entry, or a broken link,+# is caught in CI instead of silently shipping unreachable (see floci-io/floci: eleven+# services/*.md pages went live without a nav line and nothing was red).+strict: true+validation:+ nav:+ omitted_files: warn+ not_found: warn+ absolute_links: warn+ links:+ not_found: warn+ absolute_links: warn+ unrecognized_links: warn+not_in_nav: |+ configuration/application-yml.md+ design/*.md+extra_css:- assets/extra.css@@ -83,6 +100,7 @@ nav:- S3: services/s3.md- S3 Tables: services/s3tables.md- S3 Vectors: services/s3vectors.md+ - EFS: services/efs.md- DynamoDB: services/dynamodb.md- Lambda: services/lambda.md- Lambda MicroVMs: services/lambda-microvms.md@@ -100,6 +118,8 @@ nav:- IAM: services/iam.md- STS: services/sts.md- Organizations: services/organizations.md+ - Control Tower: services/controltower.md+ - AWS Service Catalog: services/service-catalog.md- ElastiCache: services/elasticache.md- MemoryDB: services/memorydb.md- RDS: services/rds.md@@ -107,15 +127,18 @@ nav:- MSK (Kafka): services/msk.md- Amazon MQ: services/amazonmq.md- Glue: services/glue.md+ - Lake Formation: services/lakeformation.md- Neptune: services/neptune.md- DocumentDB: services/docdb.md- Athena: services/athena.md+ - Redshift: services/redshift.md- Data Firehose: services/firehose.md- EventBridge: services/eventbridge.md- EventBridge Pipes: services/pipes.md- EventBridge Scheduler: services/scheduler.md- CloudWatch: services/cloudwatch.md- CloudWatch RUM: services/rum.md+ - Managed Prometheus (AMP): services/managed-prometheus.md- GuardDuty: services/guardduty.md- Connect: services/connect.md- ACM: services/acm.md@@ -148,6 +171,7 @@ nav:- CloudTrail: services/cloudtrail.md- CloudFront: services/cloudfront.md- Route53: services/route53.md+ - Route 53 Resolver: services/route53resolver.md- AWS Cloud Map: services/cloudmap.md- AWS IoT Core: services/iot.md- AppSync: services/appsync.md@@ -156,8 +180,12 @@ nav:- EMR: services/emr.md- EMR Serverless: services/emr-serverless.md- WAF v2: services/wafv2.md+ - AWS Network Firewall: services/network-firewall.md- Textract: services/textract.md- Transcribe: services/transcribe.md+ - Comprehend: services/comprehend.md+ - Rekognition: services/rekognition.md+ - Translate: services/translate.md- Pricing: services/pricing.md- Cost Explorer: services/ce.md- Cost and Usage Reports: services/cur.mddiff --git a/tools/docs/check_service_matrix.py b/tools/docs/check_service_matrix.pyindex a19b329519..1b9e3388c3 100644--- a/tools/docs/check_service_matrix.py+++ b/tools/docs/check_service_matrix.py@@ -16,6 +16,11 @@ resolves to neither - unless tools/docs/service_matrix.yaml says otherwise (an afor a key whose AWS signing name differs from its doc filename, or a time-boxeddeferred entry for a service that is genuinely not documented yet).+The reverse direction is checked too: every docs/services/*.md page must have a+matrix row, unless listed under `facet_pages:` in the registry, so a page can no+longer exist in the nav with no row (elb-classic.md did, hidden by the `elb` key+exact-matching the v2 page).+Run from anywhere in the repo:python3 tools/docs/check_service_matrix.py # print warnings onlypython3 tools/docs/check_service_matrix.py --strict # exit non-zero on warnings@@ -54,6 +59,8 @@ ALL_DESCRIPTOR_CALLS_RE = re.compile(r"(?<!ServiceDescriptor )\bdescriptor\(")# is not part of the filename and is dropped by stopping the match at `.md` itself.MATRIX_LINK_RE = re.compile(r"\]\(([a-z0-9][a-z0-9\-]*)\.md")+SERVICES_DIR = "docs/services"+@dataclass(frozen=True)class DeferredEntry:@@ -96,16 +103,27 @@ def extract_matrix_slugs(md_source: str) -> set[str]:return set(MATRIX_LINK_RE.findall(table))-def _load_registry(repo_root: Path) -> tuple[dict[str, str], list[DeferredEntry]]:- """Load service_matrix.yaml. Returns (aliases, deferred entries).+def find_unlinked_pages(services_dir: Path, slugs: set[str], facet_pages: set[str]) -> list[str]:+ """docs/services pages (by slug) that no matrix row links and no facet entry excuses.++ index.md is the matrix page itself and is never expected to link to itself.+ """+ pages = sorted(p.stem for p in services_dir.glob("*.md") if p.name != "index.md")+ return [page for page in pages if page not in slugs and page not in facet_pages]+++def _load_registry(repo_root: Path) -> tuple[dict[str, str], list[DeferredEntry], set[str]]:+ """Load service_matrix.yaml. Returns (aliases, deferred entries, facet pages).Schema: `aliases:` maps an externalKey to the doc slug that documents it;`deferred:` lists externalKeys with no row yet, each requiring `reason` and a`by` expiry date (see service_matrix.yaml's header comment for why expiry is- mandatory rather than a permanent bypass).+ mandatory rather than a permanent bypass); `facet_pages:` lists docs/services+ slugs that deliberately have no matrix row of their own."""raw = yaml.safe_load((repo_root / REGISTRY).read_text(encoding="utf-8")) or {}aliases = dict(raw.get("aliases") or {})+ facet_pages = set(raw.get("facet_pages") or [])deferred: list[DeferredEntry] = []for item in raw.get("deferred") or []:missing = [f for f in ("key", "reason", "by") if f not in item]@@ -120,7 +138,7 @@ def _load_registry(repo_root: Path) -> tuple[dict[str, str], list[DeferredEntry]by=date.fromisoformat(str(item["by"])),))- return aliases, deferred+ return aliases, deferred, facet_pagesdef find_undocumented(@@ -171,7 +189,7 @@ def main(argv: list[str] | None = None) -> int:repo_root = _repo_root()try:- aliases, deferred = _load_registry(repo_root)+ aliases, deferred, facet_pages = _load_registry(repo_root)except (ValueError, yaml.YAMLError) as exc:print(f"error: {exc}", file=sys.stderr)return 1@@ -219,6 +237,12 @@ def main(argv: list[str] | None = None) -> int:f"{MATRIX_DOC} (add a row, an alias, or a time-boxed entry in {REGISTRY})")+ for page in find_unlinked_pages(repo_root / SERVICES_DIR, slugs, facet_pages):+ warnings.append(+ f"{SERVICES_DIR}/{page}.md has no row in {MATRIX_DOC} (add a row, or list it "+ f"under facet_pages in {REGISTRY} if it is a facet of another service's page)"+ )+for w in warnings:print(f"warning: {w}", file=sys.stderr)diff --git a/tools/docs/service_matrix.yaml b/tools/docs/service_matrix.yamlindex a97ccf5934..0e8b847d08 100644--- a/tools/docs/service_matrix.yaml+++ b/tools/docs/service_matrix.yaml@@ -13,6 +13,10 @@# 3. deferred - genuinely undocumented today, tracked with a reason. A NEW# descriptor key that is neither an exact match, an alias target,# nor listed here fails `check_service_matrix.py --strict`.+#+# The reverse direction is checked too: every docs/services/*.md page must be linked+# from a matrix row unless its slug is listed under `facet_pages:` (a page that+# documents a facet of another service and deliberately has no row of its own).aliases:apigateway: api-gateway # "API Gateway v1" row title@@ -37,6 +41,7 @@ aliases:appconfigdata: appconfig # data-plane facet, at appconfig.md#data-planetagging: resource-groups-tagging # Resource Groups Tagging API's SigV4 signing nameelasticloadbalancing: elb # ELB v2's SigV4 signing name+ elb: elb-classic # Classic (2012-06-01) key; the v2 page is elb.mdapplication-autoscaling: applicationautoscalingelasticbeanstalk: elastic-beanstalkec2messages: ssm # SSM Messages facet, documented alongside ssm.md@@ -60,3 +65,6 @@ deferred:- key: bedrock-agentcore-controlreason: "documented by floci-io/floci#2436 (open at time of writing)"by: "2026-09-15"++# docs/services pages that intentionally have no Service Matrix row of their own.+facet_pages: []diff --git a/tools/docs/test_check_service_matrix.py b/tools/docs/test_check_service_matrix.pyindex 9d3c287108..2dba09b37e 100644--- a/tools/docs/test_check_service_matrix.py+++ b/tools/docs/test_check_service_matrix.py@@ -177,3 +177,25 @@ def test_find_undocumented_deferred_entry_already_resolved_is_not_flagged():)assert undocumented == []assert expired == []+++# --------------------------------------------------------------------------- #+# Unlinked pages+# --------------------------------------------------------------------------- #+def test_find_unlinked_pages_flags_a_page_with_no_row(tmp_path):+ for name in ("index.md", "ssm.md", "elb.md", "elb-classic.md"):+ (tmp_path / name).write_text("# page\n")+ # index.md is the matrix page itself; elb.md is linked; elb-classic.md is not.+ assert c.find_unlinked_pages(tmp_path, slugs={"ssm", "elb"}, facet_pages=set()) == ["elb-classic"]+++def test_find_unlinked_pages_honours_facet_exemption(tmp_path):+ for name in ("index.md", "lambda.md", "lambda-microvms.md"):+ (tmp_path / name).write_text("# page\n")+ assert c.find_unlinked_pages(tmp_path, slugs={"lambda"}, facet_pages={"lambda-microvms"}) == []+++def test_find_unlinked_pages_ignores_non_markdown(tmp_path):+ (tmp_path / "ssm.md").write_text("# page\n")+ (tmp_path / "diagram.svg").write_text("<svg/>")+ assert c.find_unlinked_pages(tmp_path, slugs={"ssm"}, facet_pages=set()) == []