Make CLI success output copy-paste-safe; add --serve, docs hub, key hygiene

A successful clone printed a bare, timestamped app path that wrapped mid-word
in the terminal, so users' `cd` failed and `npm install && npm run dev` ran in
the wrong directory — a confusing failure from a successful clone. Plus there
was no first-party "see it locally" path, no central docs page, "clone" was
conflated with `git clone`, and key hygiene wasn't stated.

CLI (compiler):
- Add compiler/src/cliSummary.ts: a copy-paste-safe success block on stderr — a
  single QUOTED `cd "<app>" && npm install && npm run dev` line that survives
  terminal wrapping — plus the AGENTS.md safe-to-edit pointers (content.ts,
  components/). The machine-readable {"event":"done",...} JSON stays on stdout.
- Add --serve (npm install + npm run dev in the generated app) and --open
  (also open the browser at the detected dev URL). Wired into single + multi.
- Add writeLatestPointer(): refresh a runs/<site>/latest symlink to the newest
  run so there's a stable, timestamp-free cd/script target. The reuse/regen
  scanners already filter to digit-prefixed run dirs, so `latest` is ignored.
- Tests: cliSummary (quoting, single-line command, Next/Vite roots, stable-path
  preference, --serve/--open hint) and runsLayout (symlink write + in-place
  refresh, timestamp-free stable path).

Docs:
- Add docs/README.md as a central documentation index.
- State prominently that ditto "cloning" = generating a codebase from a live
  URL, NOT `git clone` (no source repo required), in README + docs hub.
- Add "keys are secrets: use $DITTO_API_KEY, never inline/commit, rotate
  anytime" beside the key/auth examples in README + docs/SERVICE.md.
- Document --serve/--open and the latest symlink in README + compiler/README.

Note: the live ditto.site/docs web route and the dashboard's inline-token
snippet live in the marketing-site repo and still need a change there.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

compiler/test/cliSummary.test.ts

@@ -0,0 +1,53 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { doneSummary, shellQuote } from "../src/cliSummary.js";
+
+describe("shellQuote", () => {
+  it("wraps a path in double quotes so spaces survive copy-paste", () => {
+    assert.equal(shellQuote("/Users/x/runs/site/20260701/generated/app"), '"/Users/x/runs/site/20260701/generated/app"');
+    assert.equal(shellQuote("/Users/x/My Sites/app"), '"/Users/x/My Sites/app"');
+  });
+
+  it("escapes characters the shell would otherwise interpret inside double quotes", () => {
+    assert.equal(shellQuote('/a/"b"/$c/`d`/e\\f'), '"/a/\\"b\\"/\\$c/\\`d\\`/e\\\\f"');
+  });
+});
+
+describe("doneSummary", () => {
+  const base = { url: "https://academyux.com/", appDir: "/runs/academyux.com/20260701-173012/generated/app", framework: "next" as const };
+
+  it("emits a single quoted preview line (no mid-word wrap on the path)", () => {
+    const out = doneSummary(base);
+    const line = out.split("\n").find((l) => l.includes("cd "));
+    assert.ok(line, "has a cd line");
+    // one line, path is quoted so a wrapping terminal can't split the command
+    assert.match(line!, /cd "\/runs\/academyux\.com\/20260701-173012\/generated\/app" && npm install && npm run dev/);
+  });
+
+  it("points at the Next safe-edit areas from AGENTS.md", () => {
+    const out = doneSummary(base);
+    assert.match(out, /src\/app\/content\.ts/);
+    assert.match(out, /src\/app\/components\//);
+    assert.match(out, /AGENTS\.md/);
+  });
+
+  it("uses the Vite src root when framework is vite", () => {
+    const out = doneSummary({ ...base, framework: "vite" });
+    assert.match(out, /cd .* && npm install && npm run dev/);
+    assert.match(out, /• page copy & content {2}→ {2}src\/content\.ts/);
+    assert.match(out, /• components {11}→ {2}src\/components\//);
+  });
+
+  it("prefers the stable path as the cd target and still shows the exact run", () => {
+    const out = doneSummary({ ...base, stableAppDir: "/runs/academyux.com/latest/generated/app" });
+    const cdLine = out.split("\n").find((l) => l.includes("cd "))!;
+    assert.match(cdLine, /cd "\/runs\/academyux\.com\/latest\/generated\/app"/);
+    assert.match(out, /This exact run/);
+    assert.match(out, /\/runs\/academyux\.com\/20260701-173012\/generated\/app/);
+  });
+
+  it("mentions the --serve / --open shortcut", () => {
+    assert.match(doneSummary(base), /--serve/);
+    assert.match(doneSummary(base), /--open/);
+  });
+});

compiler/test/runsLayout.test.ts

@@ -0,0 +1,31 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, existsSync, readlinkSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeLatestPointer } from "../src/cli.js";
+
+describe("writeLatestPointer", () => {
+  it("writes latest.json and a `latest` symlink to the newest run, refreshing it in place", () => {
+    const runs = mkdtempSync(join(tmpdir(), "ditto-runs-"));
+    const siteId = "example.com";
+
+    const run1 = join(runs, siteId, "20260701-100000");
+    mkdirSync(join(run1, "generated", "app"), { recursive: true });
+    const stable1 = writeLatestPointer(runs, siteId, run1);
+
+    assert.ok(existsSync(join(runs, siteId, "latest.json")), "writes latest.json breadcrumb");
+    assert.ok(stable1 && existsSync(stable1), "returned stable app path resolves through the symlink");
+    assert.equal(realpathSync(readlinkSync(join(runs, siteId, "latest"))), realpathSync(run1));
+
+    // A second run must re-point the existing symlink, not throw on the collision.
+    const run2 = join(runs, siteId, "20260701-200000");
+    mkdirSync(join(run2, "generated", "app"), { recursive: true });
+    const stable2 = writeLatestPointer(runs, siteId, run2);
+
+    assert.equal(realpathSync(readlinkSync(join(runs, siteId, "latest"))), realpathSync(run2));
+    assert.ok(stable2 && existsSync(stable2));
+    // The stable path is timestamp-free (goes through `latest`, not the run's timestamp).
+    assert.match(stable2!, /example\.com\/latest\/generated\/app$/);
+  });
+});