Merge pull request #11 from ion-design/codex/readme-methodology-link

[codex] Add methodology doc and homepage link

README.md

@@ -2,7 +2,7 @@
   <img src="docs/assets/ditto.svg" alt="ditto.site logo" width="112" />
 </p>
 
-# ditto.site
+# [ditto.site](https://ditto.site)
 
 [![CI](https://github.com/ion-design/ditto.site/actions/workflows/ci.yml/badge.svg)](https://github.com/ion-design/ditto.site/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -15,6 +15,9 @@ Router project by default, or Vite React when requested.
 The compiler is not an LLM page author. It is a capture-to-code pipeline: same
 frozen capture in, byte-stable app out.
 
+Read the public development and evaluation method in
+[docs/METHODOLOGY.md](docs/METHODOLOGY.md).
+
 ## Usage
 
 - REST API: `https://api.ditto.site`
@@ -222,7 +225,8 @@ observed safely. Unsupported app logic, auth, payments, personalization, and
 arbitrary third-party JavaScript are not replayed.
 
 For the detailed service API, see [docs/SERVICE.md](docs/SERVICE.md). For
-deployment, see [docs/DEPLOY.md](docs/DEPLOY.md).
+deployment, see [docs/DEPLOY.md](docs/DEPLOY.md). For the development method
+behind the compiler, see [docs/METHODOLOGY.md](docs/METHODOLOGY.md).
 
 Hosted deployments should keep `/v1/clones*` and `/mcp` behind API-key auth.
 When `SIGNUP_ENABLED=true` in DB mode, the Resend-backed
@@ -241,7 +245,7 @@ minting is intentional.
 | `packages/db/` | Drizzle schema, migrations, repository, and queue wrapper |
 | `packages/storage/` | local and S3/R2 artifact storage |
 | `packages/worker/` | queued clone runner and optional verification |
-| `docs/` | service, deployment, release, and responsible-use docs |
+| `docs/` | methodology, service, deployment, release, and responsible-use docs |
 | `examples/` | benchmark results and visual evidence |
 
 ## Responsible Use

docs/METHODOLOGY.md

@@ -0,0 +1,76 @@
+# Methodology
+
+ditto.site is built as a deterministic capture-to-code compiler. The goal is not
+to author a plausible page from a prompt; it is to preserve what a browser
+actually rendered and turn that evidence into a runnable app with repeatable
+output.
+
+## Principles
+
+- **Observed evidence first.** The compiler starts from browser-captured DOM,
+  computed styles, layout boxes, CSS, assets, fonts, metadata, screenshots, and
+  interaction or motion signals when they can be observed safely.
+- **Deterministic output.** A frozen capture should produce byte-stable app
+  output. Randomness, timestamps, network state, and heuristic ordering are kept
+  out of generated files.
+- **Generated code over screenshots.** The output is a Next.js or Vite React app
+  with local assets, route modules, metadata, CSS, and small runtime helpers for
+  recognized interactions. Screenshots are used for validation, not delivery.
+- **No private app replay.** Authenticated state, payments, personalization,
+  business logic, arbitrary third-party scripts, and access-controlled content
+  are not recreated.
+- **Safety is part of correctness.** SSRF controls, rate limits, artifact
+  boundaries, and responsible-use limits are treated as part of the system, not
+  deployment afterthoughts.
+
+## Development Loop
+
+1. **Capture a representative fixture or benchmark page.** The browser capture
+   records the rendered page and the artifacts needed to reconstruct it.
+2. **Normalize into a render IR.** Capture data is converted into stable
+   sections, tokens, assets, semantic metadata, and interaction candidates.
+3. **Generate the app.** The generator emits framework files, styles, assets,
+   route structure, metadata, runtime helpers, and handoff docs.
+4. **Validate by building and rendering.** Browser-backed checks compare source
+   and clone behavior, including structure, screenshots, links, SEO metadata,
+   responsive layout, interactions, and motion where supported.
+5. **Lock regressions with focused tests.** Changes that affect compiler output
+   should add or update a fixture, unit test, or benchmark note so the behavior
+   remains explainable.
+6. **Keep the service wrapper thin.** The REST, MCP, queue, database, and storage
+   packages call the compiler through the public barrel instead of reaching into
+   compiler internals.
+
+## Validation Gates
+
+The repository uses small, repeatable gates rather than one broad visual score:
+
+- TypeScript typechecking across every workspace.
+- Node test suites for compiler output, API behavior, storage, cache keys, SSRF,
+  auth, MCP contracts, and queue/worker paths where infrastructure is available.
+- Browser-gated fixture tests through Playwright and Chromium.
+- Determinism checks that regenerate from one frozen capture and compare output.
+- Optional benchmark runs for broader visual or route coverage.
+
+Heavy real-site benchmark sweeps are kept outside the default CI path. CI should
+stay fast enough to run on every pull request; broader benchmark evidence is
+attached when a change materially affects clone output.
+
+## Review Standard
+
+Compiler changes should answer three questions:
+
+- What new source evidence is captured or interpreted?
+- How does generation stay deterministic?
+- Which fixture, test, or benchmark proves the behavior?
+
+Service changes should keep the hosted API and MCP contracts stable, preserve
+auth and SSRF guarantees, and avoid changing compiler semantics from the service
+layer.
+
+## Safety Boundaries
+
+See [RESPONSIBLE_USE.md](RESPONSIBLE_USE.md) and [SECURITY.md](../SECURITY.md)
+for the public-use and deployment controls. Changes that make phishing,
+impersonation, access-control bypass, unbounded third-party capture, or unsafe
+fetching easier are out of scope for this project.