[williamloo-scale]

Stacked on #444.

A website spec: one TOML file declares a site, composes from parts, and checks any server against it. Design: docs/website-spec.md.

• agentenv_protocol.website.spec reads [site], [source], [data], [users], [roles], [routes.ops], [state], [clock], [[uses]] and extends, with validation, overlays, composition, card params, from_card, from_environment, a JSON Schema and a CLI (validate, show, show --card).
• A name table for a multi env: synthetic over live over the allowlist, two sites of one kind on a name refused.
• @website(spec="website.toml"): the class is refused when its @api routes aren't the spec's, and its card is built from the spec. Notes now declares itself this way.
• env.toml takes spec = "website.toml" or an inline [spec]; the env takes its name, health path and domains from it.
• conformance --spec checks a server's card and routes against the spec; those checks are required.
• Examples in examples/website/specs/: a replayed Slack overlay, an intranet, and an SSO component.

Live and replay sources, served_by and models = "mcp:..." are modelled in the spec but not deployable from env.toml yet.

Test

Unit suite: 12,793 passed (one GitHub-clone test from main, which hangs on the local machine on main too, deselected).

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, with a non-blocking error-reporting issue for malformed specs.

Findings

1.  Mistyped specs crash validation ▶

Fix with agent prompt

### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/website/spec/__init__.py:577-580
A file containing `extends = "base.toml"` and `uses = 1` reaches this loop before `_validated()` and raises `TypeError`. An inherited `data.collections = [1]` in another folder similarly crashes `_rebased()` at `.values()`.

The CLI and bundle authoring catch only `SpecError`, so authors get a traceback instead of an error naming the bad field. Check these types before merging and rebasing, or turn these failures into `SpecError`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds one website spec for declarations, overlays, components, cards, bundle authoring, and conformance checks.

• A website TOML file now defines and composes a site's contract.
• Website SDK classes can now take their site contract from a spec.
• Website environments can now take their name and domains from a spec.
• Conformance checks can now compare a server with a website spec.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  TOML[Website spec] --> Resolve[Merge overlays and components]
  Resolve --> Spec[Resolved spec]
  Spec --> SDK[Check SDK class]
  SDK --> Card[Serve website card]
  Spec --> Bundle[Read env name, health and domains]
  Spec --> Check[Check any server]
  Card --> Check

Loading

_{Reviews (7) · Last reviewed commit: "Merge wloo/website-sdk-followups into wl..." · Reviewed by Greptile}

[greptile-apps]

Mistyped specs crash validation

A file containing extends = "base.toml" and uses = 1 reaches this loop before _validated() and raises TypeError. An inherited data.collections = [1] in another folder similarly crashes _rebased() at .values().

The CLI and bundle authoring catch only SpecError, so authors get a traceback instead of an error naming the bad field. Check these types before merging and rebasing, or turn these failures into SpecError.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/website/spec/__init__.py
Line: 577-580

Comment:
**Mistyped specs crash validation**

A file containing `extends = "base.toml"` and `uses = 1` reaches this loop before `_validated()` and raises `TypeError`. An inherited `data.collections = [1]` in another folder similarly crashes `_rebased()` at `.values()`.

The CLI and bundle authoring catch only `SpecError`, so authors get a traceback instead of an error naming the bad field. Check these types before merging and rebasing, or turn these failures into `SpecError`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.