Give agents a system, not a blank canvas

Autonomy needs a usable map

An agent with write access to a website repository can produce a new page quickly. That does not mean it knows which layout patterns are already trusted, which content fields are safe, where visual decisions belong, which routes are public, or what browser behavior must hold after the edit.

Without a local contract, more autonomy mostly means more opportunities to create plausible inconsistency.

The useful alternative is not a giant prompt full of warnings. It is a repository that explains itself through machine-readable choices:

• page and component JSON Schemas;
• a catalog that says when to use and avoid each pattern;
• examples derived from the same manifests as validation;
• semantic theme roles rather than arbitrary styling values;
• exact diagnostics when a file violates the contract;
• build and browser gates that test the resolved site rather than the agent's confidence.

Constrain implementation, not meaning

Bad constraints merely move complexity around. A page builder made from dozens of layout primitives still asks the author to make responsive and semantic decisions one tiny block at a time.

Sights exposes larger intent-based components. A hero introduces. A comparison table evaluates the same criteria. Process steps preserve order. Editorial media balances one story with one image. A showcase gives a few visual outcomes more room.

The author still controls the message, sequence, evidence, destinations, and approved media. The component controls heading structure, responsive layout, native semantics, and interaction behavior.

That boundary is the leverage.

Make the valid path discoverable

An agent should not have to infer component props by reading renderer code. Each Sights manifest publishes the same facts to both machines and people:

1. the stable component name;
2. its purpose and nearby alternatives;
3. a strict props schema;
4. semantic variants;
5. accessibility requirements;
6. client and server runtime declarations;
7. validated examples;
8. a generated catalog thumbnail and review route.

The result is a much better editing loop: inspect the catalog, make a small structured change, validate, and respond to precise feedback.

Failure should teach the system

"Invalid page" is not a useful diagnostic. A good failure names the file, JSON Pointer, received value, expected contract, and likely fix. Unknown component names should suggest close matches. Broken internal links should name the missing canonical route. A link to an internal review page should explain why visibility rules reject it.

Actionable failures do more than block bad output. They help the author build a correct mental model of the system.

Trusted code remains available

Constrained content does not make the platform closed. When a site genuinely needs a new interaction or presentation responsibility, trusted code can register a custom component.

The custom path stays explicit: strict schema, renderer, examples, documentation, semantic thumbnail, accessibility contract, and declared runtime. The page can reference the capability by name, but it cannot become the capability's source code.

That is how Sights gives agents broad autonomy over ordinary website work without turning every content edit into an application-code change.