docs + fix: working terraform example, IAM policy, and silent-failure docs

[jcastiarena]

Summary

During a real-world installation of this scope on AWS (Banco Galicia POC, end-to-end SPA deploy), the terraform example in specs/terraform/ did not work out of the box and several failure modes had no docs. This PR makes the example work and documents the gaps.

All problems were found in order by trying to register the scope and roll a SPA through start-initial; the deploy succeeded on the sixth attempt, each retry surfacing the next gap.

Commits

1. fix(example) — complete provider_config.attributes with nested provider/network/distribution, switch type from UUID to slug, pin module ref to main (the previous feature/remove-org-nrn ref no longer exists in nullplatform/tofu-modules).
2. docs — add static-files/docs/agent-iam-policy-example.json, a ready-to-attach IAM policy for the agent role.
3. docs(readme) — add a new top-level section "Registering and Using the Scope" (pre-requisites, registration walk-through, IAM matrix, state management, gotchas).
4. fix(scope-configuration) — the IRSA label shown in the UI listed IAM actions per service but was missing route53:GetChange and acm:GetCertificate. Added both and pointed the operator at the new example policy.

Silent failures documented

Three cases where the scope accepts input that looks valid but fails later in the workflow:

• nullplatform_provider_config.type accepts anything but only resolves slugs at runtime — passing the UUID fails mid-apply with no specification found for slug: <UUID>.
• scope_type.description is validated against a 60-char cap by the backend but not by the schema — custom descriptions over that length fail at create with a 400.
• provider_config.attributes is not validated against scope-configuration.json.tpl at create time. An incomplete config (e.g., missing network layer) only surfaces when the first scope's start-initial rolls back with "network layer is not configured for provider 'aws'".

Easy-to-miss IAM actions

Two IAM actions the agent needs that were not in the module's default policy nor documented anywhere:

• route53:GetChange on arn:aws:route53:::change/* — the AWS provider polls this while waiting for DNS propagation. Without it, the deploy fails with AccessDenied after creating the record. Confusing failure mode.
• acm:GetCertificate — required in addition to DescribeCertificate for CloudFront certificate lookup. Without it the deploy fails with a 400 on an existing, validated cert.

Pre-requisites that the scope validates but does not create

Documented in the README as pre-requisites:

• S3 state bucket
• Route 53 hosted zone
• ACM certificate in us-east-1 covering the scope's domain
• App-assets S3 bucket with a CloudFront OAC bucket policy (policy JSON included inline in the README)
• Agent IAM role (example policy added as a file)

Test plan

• tofu fmt -recursive and tofu init -backend=false work against the updated specs/terraform/.
• Apply the updated example against a clean nullplatform account and AWS account, verify the scope type registers and a test SPA deploys end-to-end.
• Verify the new README sections render correctly on GitHub.
• Verify the scope-configuration.json.tpl still parses (UI label renders the updated markdown).

---

🤖 Generated with Claude Code