How Sights works
A dependable site is a sequence of contracts, not one heroic prompt.
Sights makes the work legible from the first brief to the final static artifact. Human and AI collaborators operate on the same versioned source, generated documentation, validation rules, and browser-tested review surface.
End-to-end workflow
Eight steps from facts to a verified release.
The exact site will vary. The order protects the same fundamentals: factual content, reusable structure, semantic design, explicit capabilities, and production verification.
Clean repository boundary
The platform and the site own different kinds of change.
Sights is an installable package. A consumer proves it can remain independent instead of becoming a folder of coupled platform code.
| Responsibility | Sights packageReusable contracts and behavior | Consumer repositorySite identity and approved content |
|---|---|---|
| Components | Built-in manifests and renderers | Site-owned custom capabilities |
| Content | Schemas and validation | Pages, records, Markdown, assets |
| Presentation | Semantic token contract | Validated theme and local fonts |
| Routes | Standard rendering and static essentials | Public information architecture |
| Quality | Shared audits and component coverage | Site-specific browser assertions |
| Deployment | Portable artifacts and adapters | Host choice and release configuration |
Compounding improvement
Every real site can improve the shared system without becoming dependent on it.
When a consumer reveals a missing semantic variant, responsive edge case, accessibility failure, or repeated content pattern, the fix belongs at the narrowest reusable layer.
Platform changes then return to the canonical demo, where the component viewer, style guide, generated catalogs, production build, and browser gate keep the new behavior visible and tested.
- Site factKeep unique copy, brand, assets, route structure, and domain vocabulary in the consumer.
- Reusable behaviorPromote repeated component responsibility, schema vocabulary, and cross-site quality coverage into Sights.
- Review evidenceUse a live consumer route plus internal component and theme surfaces to show both the outcome and the contract.
Workflow questions
What changes during normal site work?
Does every page require code?
No. Most pages are created or revised by editing JSON content and local assets, with Markdown for substantial prose. Component and shell code remain unchanged.
How does an agent know what is allowed?
The consumer contains generated schemas, catalogs, examples, and an agent guide derived from the live platform manifests. Validation provides exact feedback when a choice is invalid.
When does the platform package need to change?
Only when the site exposes a genuinely reusable gap or shared defect. Unique site behavior can remain a custom component inside the consumer.
How are concurrent changes reviewed safely?
Material work uses isolated multi-repository streams with their own Sights dependency, consumer branch, preview port, handoff, and serialized integration step.
Put the workflow to use
Start with the smallest complete Sights site.
The getting-started guide shows the repository shape, authoring sequence, core commands, and first useful page contract.