@getrefino/onboarding 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refino contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @getrefino/onboarding
+
+The engine behind `npx @getrefino/cli init`: deterministic repository
+inspection, copy discovery, migration planning, agent-instruction generation,
+safe setup and verification for installing **Refino** into an existing React
+site.
+
+Development tooling only — nothing here runs inside a site. Most people want
+the CLI instead:
+
+```bash
+npx @getrefino/cli init
+```
+
+```ts
+import { inspectRepository, planMigration, applyPlan, renderAgentInstructions, verifyIntegration } from "@getrefino/onboarding";
+
+const inspection = inspectRepository("/path/to/site");
+const plan = planMigration(inspection, { routes: ["/"] });
+applyPlan(appDirectory(inspection), plan, { dryRun: true });
+const markdown = renderAgentInstructions(plan);
+const result = verifyIntegration("/path/to/site");
+```
+
+All results are plain JSON. No network calls, no model calls. It never rewrites
+JSX and never overwrites an existing file.
+
+<https://refino.dev>

package/dist/agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render repository-specific instructions for a coding agent from a plan.
+ * Every fact in the output comes from the plan; nothing is generic filler.
+ */
+import { INSTRUCTIONS_FILE } from "./plan.js";
+import type { MigrationPlan } from "./types.js";
+export declare function renderAgentInstructions(plan: MigrationPlan): string;
+export { INSTRUCTIONS_FILE };

package/dist/agent.js

@@ -0,0 +1,219 @@
+/**
+ * Render repository-specific instructions for a coding agent from a plan.
+ * Every fact in the output comes from the plan; nothing is generic filler.
+ */
+import { BOILERPLATE_DIR, CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE } from "./plan.js";
+function bullet(items) {
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function table(rows, header) {
+    const escape = (cell) => cell.replace(/\|/g, "\\|").replace(/\n/g, " ");
+    return [`| ${header.join(" | ")} |`, `| ${header.map(() => "---").join(" | ")} |`, ...rows.map((row) => `| ${row.map(escape).join(" | ")} |`)].join("\n");
+}
+function truncate(text, max = 60) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function location(candidate) {
+    return `${candidate.file}:${candidate.line}`;
+}
+/**
+ * The endpoint files for the detected host. When the tool generated them the
+ * agent only deploys them; otherwise it mounts the generated request handlers
+ * (one Request in, one Response out) in the host's own format.
+ */
+function endpointSteps(plan) {
+    const { repository, integration } = plan;
+    const host = integration.host;
+    const ext = repository.language === "typescript" ? "ts" : "js";
+    const handlersModule = `${BOILERPLATE_DIR}/request-handlers.${ext}`;
+    const facts = host.notes.map((note) => `Runtime facts: ${note}`);
+    if (plan.refino) {
+        return [
+            `There is **no copy endpoint and no login to write**: this site is connected to Refino (site \`${plan.refino.siteId}\` at ${plan.refino.appUrl}). The browser loads and saves through \`${host.copyEndpoint}\` with a short-lived editor token that \`${BOILERPLATE_DIR}/refino-client.${ext}\` obtains from Refino, and Refino commits to the repository. Do not create \`/api/copy\`, \`/api/edit-session\`, serverless functions, an editor password, a session secret or a repository token, and do not add any \`EDITOR_*\` or \`COPY_*\` environment variable.`,
+            ...facts,
+        ];
+    }
+    if (host.generated) {
+        return [
+            `The endpoint files were generated: \`${host.copyEndpoint}\` (GET/POST /api/copy) and \`${host.sessionEndpoint}\` (GET probe, POST login, DELETE logout for /api/edit-session). Each is a few lines that pass the request and the runtime's environment object to \`${handlersModule}\`, which holds the session check, cross-site rejection, password login and persistence. Read them once; do not rewrite them and do not add handlers of your own next to them.`,
+            ...facts,
+        ];
+    }
+    const contract = `The behaviour is already implemented in \`${handlersModule}\`: \`handleCopyRequest(request, env)\` and \`handleEditSessionRequest(request, env)\` take a standard \`Request\` and an environment object (\`process.env\`, or the runtime's per-request env) and return a \`Response\`. Do not reimplement the session check, cookie or persistence logic; only adapt the host's signature.`;
+    switch (host.kind) {
+        case "next-api-routes":
+            return [
+                `Create \`${host.copyEndpoint}\` and \`${host.sessionEndpoint}\` as Pages Router API routes. ${contract} In each route build a \`Request\` from \`req\` (method, \`http://\${req.headers.host}\${req.url}\`, headers, and the raw body for POST; export \`config = { api: { bodyParser: false } }\` so the body is available as a stream), call the handler with \`process.env\`, then copy the Response's status, headers (including \`set-cookie\`) and body to \`res\`.`,
+                ...facts,
+            ];
+        case "custom-server":
+            return [
+                `In the existing server (${repository.server}), mount \`GET/POST /api/copy\` and \`GET/POST/DELETE /api/edit-session\` at \`${host.copyEndpoint}\` and \`${host.sessionEndpoint}\`. ${contract} Frameworks with Web-standard handlers (Hono, h3, Bun) pass the request straight through; Express-style servers build a \`Request\` from \`req\` and write the \`Response\` back.`,
+                ...facts,
+            ];
+        default:
+            return [
+                `This site has no server and no hosting provider was identified. Add one function per route, \`${host.copyEndpoint}\` for /api/copy and \`${host.sessionEndpoint}\` for /api/edit-session, in the format your host expects. ${contract} If no serverless option exists, stop and report that saving requires a server.`,
+                ...facts,
+            ];
+    }
+}
+function frameworkSteps(plan) {
+    const { integration, repository } = plan;
+    const ext = repository.language === "typescript" ? "ts" : "js";
+    const jsx = repository.language === "typescript" ? "tsx" : "jsx";
+    const steps = [];
+    if (plan.refino) {
+        const editPage = plan.files.find((file) => /(^|\/)edit(\/page)?\.\w+$/.test(file.path) && !file.path.startsWith(`${BOILERPLATE_DIR}/`))?.path;
+        steps.push(`Open \`${integration.provider.file ?? "the root component"}\`. Import \`copy\` from \`${plan.contentFile.path}\` and \`CopyEditing\` from \`${BOILERPLATE_DIR}/copy-editing.${jsx}\`, and wrap everything it renders in \`<CopyEditing content={copy}>\` (\`{children}\` **and every component the layout or root renders itself**, because an \`EditableText\` outside the provider displays its id as text). Pass no \`editing\` prop and do not import \`next/headers\`: edit mode is decided in the browser from the Refino editor session, so the server never reads a cookie and pages can stay static. Change nothing else there.`, editPage
+            ? `The owner's entry point \`${editPage}\` was generated (it renders \`${BOILERPLATE_DIR}/edit-page.${jsx}\`, a client component that sends the owner to Refino and finishes the authorization when Refino sends them back). Read it once; do not rewrite it.`
+            : `Add a route for \`/edit\` that renders the default export of \`${BOILERPLATE_DIR}/edit-page.${jsx}\` (for react-router: \`<Route path="/edit" element={<EditPage />} />\`; for a single-page app: render it when \`window.location.pathname === "/edit"\`). It is the owner's entry point: it sends them to Refino and finishes the authorization when Refino sends them back to \`/edit?code=…&state=…\`. Do not put it behind any other navigation.`, ...endpointSteps(plan));
+        return steps;
+    }
+    if (integration.provider.strategy === "next-app-root-layout-client-session") {
+        steps.push(`Open \`${integration.provider.file}\`. Import \`copy\` from \`${plan.contentFile.path}\` and \`CopyEditing\` from \`${BOILERPLATE_DIR}/copy-editing.${jsx}\`, and wrap the body's content in \`<CopyEditing content={copy}>\`: \`{children}\` **and every component the layout renders itself** (a header, nav or footer placed next to \`{children}\`), because an \`EditableText\` outside the provider displays its id as text. Pass no \`editing\` prop and do not import \`next/headers\`: ${repository.serverNotes[0] ?? "the site is a static export"} The generated wrapper asks \`GET /api/edit-session\` in the browser and turns edit mode on only for a 204. Change nothing else in the layout.`, `The static login page \`${plan.files.find((file) => /\/edit\/page\.\w+$/.test(file.path))?.path ?? "app/edit/page.tsx"}\` and its \`layout\` (noindex) were generated; read them once, do not rewrite them. Do not create route handlers under \`app/api\`: they cannot be exported.`, ...endpointSteps(plan));
+        return steps;
+    }
+    switch (repository.router) {
+        case "next-app":
+            steps.push(`Open \`${integration.provider.file}\`. Import \`copy\` from \`${plan.contentFile.path}\`, \`CopyEditing\` from \`${BOILERPLATE_DIR}/copy-editing.${jsx}\` and \`isEditorAuthenticated\` from \`${BOILERPLATE_DIR}/editor-session.${ext}\`. Make the layout \`async\`, compute \`const editing = await isEditorAuthenticated()\`, and wrap the body's content in \`<CopyEditing content={copy} editing={editing}>\`: \`{children}\` **and every component the layout renders itself** (a header, nav or footer placed next to \`{children}\`), because an \`EditableText\` outside the provider displays its id as text. Change nothing else in the layout.`, ...endpointSteps(plan), `The \`/edit\` login page was generated next to the route handlers. If the site already has an owner login, replace the body of \`isEditorAuthenticated()\` in \`${BOILERPLATE_DIR}/editor-session.${ext}\` and of \`isEditorRequest()\` in \`${BOILERPLATE_DIR}/request-handlers.${ext}\` with that check, and delete the generated login page and edit-session route.`);
+            break;
+        case "next-pages":
+            steps.push(`Open \`${integration.provider.file}\`. Wrap \`<Component {...pageProps} />\` with \`<RefinoProvider content={copy} editing={pageProps.refinoEditing === true} endpoint="/api/copy" onExit={...}>\`. Add \`getServerSideProps\` (or extend the existing one) on the selected pages to set \`refinoEditing\` to \`verifySessionToken(config, sessionTokenFromCookieHeader(req.headers.cookie))\` with \`config = readEditorAuthConfig()\` (false when the config is null), all from \`${BOILERPLATE_DIR}/editor-auth.${ext}\`.`, ...endpointSteps(plan));
+            break;
+        default:
+            steps.push(`Open \`${integration.provider.file ?? "the root component"}\`. Wrap the app's root element with \`<CopyEditing content={copy}>\` from \`${BOILERPLATE_DIR}/copy-editing.${jsx}\`, where \`copy\` is imported from \`${plan.contentFile.path}\`. The wrapper asks \`GET /api/edit-session\` in the browser and turns edit mode on only for a 204 response. Never derive edit mode from the URL.`);
+            steps.push(...endpointSteps(plan));
+    }
+    return steps;
+}
+export function renderAgentInstructions(plan) {
+    const selected = plan.copy.filter((candidate) => candidate.status === "selected");
+    const review = plan.copy.filter((candidate) => candidate.status === "needs-review");
+    const unsupported = plan.copy.filter((candidate) => candidate.status === "unsupported");
+    const filesToEdit = [...new Set([...selected, ...review].map((candidate) => candidate.file))].sort();
+    const { repository, integration } = plan;
+    const sections = [];
+    sections.push(`# Make this site visually editable with Refino
+
+These instructions were generated by \`refino\` from an inspection of this
+repository on ${plan.generatedAt.slice(0, 10)}. The facts below were read from the
+files themselves. Trust them unless the source in front of you contradicts them,
+and if it does, follow the source and mention the discrepancy in your report.
+
+Machine-readable version of this plan: \`${PLAN_FILE}\`.
+
+## What you are doing
+
+Installing Refino into this site. Refino lets the site owner edit visible
+website copy in the browser while this repository stays the source of truth.
+
+After this work the owner can sign in, click any migrated sentence on the real
+page, rewrite it, and save it back to \`${plan.contentFile.path}\`, which is the
+single source of truth for that copy. An edit is a commit. There is no CMS, no
+database and no sync step. You are not changing what the site says, how it
+looks, or how it works.
+
+These instructions are authoritative. Follow them rather than inventing your own
+integration: the inspection, the plan and the generated files above were
+produced by \`npx @getrefino/cli init\` from this exact repository.
+
+## Facts about this repository
+
+${bullet([
+        `Framework: ${repository.framework}${repository.next ? ` (next ${repository.next})` : ""}, router: ${repository.router}`,
+        `Language: ${repository.language}; React ${repository.react ?? "unknown"}`,
+        `Package manager: ${repository.packageManager}`,
+        `App root: \`${repository.appRoot}\`${repository.appRoot !== "." ? " (monorepo; all paths below are relative to it)" : ""}`,
+        `Provider location: \`${integration.provider.file ?? "unknown"}\` (${integration.provider.strategy})`,
+        `Mode: ${plan.refino ? `Refino-hosted (site \`${plan.refino.siteId}\`, app ${plan.refino.appUrl}; no site secrets, no server code)` : "self-hosted (this deployment runs its own login and copy endpoint)"}`,
+        `Copy endpoint: \`${integration.endpoint.path}\` (${integration.endpoint.kind})`,
+        `Host integration: ${integration.host.kind}${plan.refino ? " (Refino serves the copy API; nothing to deploy)" : integration.host.generated ? " (endpoint files generated)" : " (agent mounts the generated request handlers)"}`,
+        plan.refino ? `Server capability: ${repository.server} (not needed for editing: Refino serves the copy API)` : `Server capability: ${repository.server}${repository.serverNotes.length > 0 ? ` — ${repository.serverNotes.join(" ")}` : ""}`,
+        `Authentication: ${integration.auth.existing.length > 0 ? integration.auth.existing.join(", ") : "none detected"} → strategy \`${integration.auth.strategy}\``,
+        `Hosting: ${repository.hosting ?? "not identified"}`,
+        `Git: ${repository.git.isRepository ? `branch ${repository.git.branch ?? "?"}${repository.git.github ? `, GitHub ${repository.git.github.owner}/${repository.git.github.repo}` : ""}${repository.git.clean === false ? ", uncommitted changes present" : ""}` : "not a git repository"}`,
+        `Verification commands: ${plan.verification.commands.length > 0 ? plan.verification.commands.map((command) => `\`${command}\``).join(", ") : "none defined in package.json scripts"}`,
+    ])}
+
+## Scope
+
+Migrate only: ${plan.scope.description}
+
+${selected.length} strings are selected, ${review.length} need your judgment, ${unsupported.length} are unsupported as plain text, ${plan.summary.excluded} were excluded as not copy.
+
+Files you will edit for copy: ${filesToEdit.map((file) => `\`${file}\``).join(", ") || "none"}.`);
+    sections.push(`## Already done for you (generated files)
+
+${bullet(plan.files.map((file) => `\`${file.path}\` — ${file.action}: ${file.description}`))}
+
+If any of these files are missing, run \`npx @getrefino/cli init --agent --yes\` in \`${repository.appRoot}\` before continuing, or create them by hand from \`${PLAN_FILE}\`.`);
+    sections.push(`## Steps
+
+1. **Install dependencies.** \`${plan.repository.packageManager === "unknown" ? "npm install" : plan.repository.packageManager === "pnpm" ? "pnpm install" : plan.repository.packageManager === "yarn" ? "yarn install" : plan.repository.packageManager === "bun" ? "bun install" : "npm install"}\` (the ${plan.refino ? "two" : "three"} \`@getrefino/*\` packages were added to \`${plan.files.find((file) => file.path.endsWith("package.json"))?.path ?? "package.json"}\`).
+2. **Wire the provider and endpoint.**
+${frameworkSteps(plan)
+        .map((step) => `   - ${step}`)
+        .join("\n")}
+3. **Replace the selected strings with \`EditableText\`.** For each row in the table below, open the file at the line, and replace the literal with \`<EditableText id="<id>" as="<tag>" ...sameProps />\` keeping the exact element type, className and every other prop. Import \`EditableText\` from \`@getrefino/react\`. The text itself must not change; it already lives in \`${plan.contentFile.path}\` under that id.
+   - For text that is the child of a component you must not replace (\`<Button>Get started</Button>\`, a \`<Link>\`, a role component such as \`<Eyebrow>\`), pass \`<EditableText id="…" />\` as the child. It renders an attribute-less inline \`<span>\` in normal mode; that span is expected and changes nothing visible, in layout or for assistive technology. Do not restructure the component to avoid it.
+   - For \`jsx-attribute\` rows (a string passed as a prop to a component), change the component so it renders that prop through \`EditableText\`, or pass \`<EditableText id="…" />\` as the prop value if the component renders it as children. Keep the element the component uses.
+   - For \`data-object\` rows (strings inside an array the file maps over), either replace the string field with the id and render it through \`<EditableText id={item.titleId} …/>\`, or keep the array and render \`<EditableText id={\`${"${prefix}"}.\${item.key}.title\`} />\` when the ids follow a pattern. Do not duplicate the text in both places.
+4. **Decide the needs-review rows.** Each one says why it needs you: usually a placeholder id (ordinal suffix or text-derived key). Rename the id to something semantic, keep the same prefix, and update \`${plan.contentFile.path}\` to match. Skip a row entirely if it is not user-visible copy.
+5. **Leave unsupported rows in code.** They mix markup or interpolation. Do not restructure sentences to make them editable.
+6. **Run verification:** \`npx @getrefino/cli verify\`${plan.verification.commands.length > 0 ? ` then ${plan.verification.commands.map((command) => `\`${command}\``).join(", ")}` : ""}. Fix only what verification reports, then run it again until it passes.
+7. **Report** using the format at the end.`);
+    sections.push(`## Selected strings (${selected.length})
+
+${selected.length > 0 ? table(selected.map((candidate) => [candidate.id ?? "", location(candidate), candidate.element ?? candidate.key ?? "", candidate.source, truncate(candidate.text)]), ["id", "file:line", "element", "source", "text"]) : "_none_"}`);
+    if (review.length > 0) {
+        sections.push(`## Needs your judgment (${review.length})
+
+${table(review.map((candidate) => [candidate.id ?? "(none)", location(candidate), candidate.element ?? candidate.key ?? "", truncate(candidate.text, 40), candidate.reason]), ["proposed id", "file:line", "element", "text", "why"])}`);
+    }
+    if (unsupported.length > 0) {
+        sections.push(`## Unsupported as plain text (${unsupported.length})
+
+${table(unsupported.map((candidate) => [location(candidate), candidate.element ?? "", truncate(candidate.text, 40), candidate.classification]), ["file:line", "element", "text", "why"])}
+
+Leave these as they are. Mention them in your report so the owner knows they are not editable yet.`);
+    }
+    sections.push(`## Rules
+
+${bullet([
+        "Do not change any copy. The strings move from JSX to the JSON file byte for byte.",
+        "Do not change styling, element types, class names, layout or behavior. `EditableText` in normal mode renders exactly the element you give it.",
+        "Do not touch files outside the ones named here except to add imports the steps require.",
+        "Do not migrate strings that are not listed, and do not migrate needs-review or unsupported rows just to increase coverage.",
+        `Do not create a second copy of the content anywhere (no context objects, no CMS, no duplicated constants). \`${plan.contentFile.path}\` is canonical.`,
+        ...(plan.refino
+            ? [
+                `Do not add any server-side editor code, environment variable or credential: Refino provides authentication, authorization, entitlement and the copy API for site \`${plan.refino.siteId}\`. Never import \`@getrefino/github\` or \`@getrefino/core/local-file\`.`,
+                "Edit mode comes only from the Refino editor session that `/edit` establishes in the browser (sessionStorage, 12 hours, one site). Never from `?edit=1`, localStorage or a hard-coded `true`.",
+                "Keep the existing deployment setup; the site keeps working as a static export.",
+            ]
+            : [
+                "Do not import `@getrefino/github`, `@getrefino/core/local-file`, or the generated `content-adapter`/`editor-auth`/`request-handlers` modules from any client component or browser bundle.",
+                "Never expose `COPY_GITHUB_TOKEN`, `EDITOR_PASSWORD` or `EDITOR_SESSION_SECRET` to the client, and never prefix them with `NEXT_PUBLIC_` or `VITE_`.",
+                "Edit mode must come from an authenticated server check of the session: either a server-rendered `editing` flag or the generated wrapper's `GET /api/edit-session` probe. Never from `?edit=1`, localStorage or a hard-coded `true`.",
+                "Keep the existing deployment setup. Persistence defaults to the local file in development; production uses `COPY_ADAPTER=github` with the variables documented in `.env.example`.",
+            ]),
+        `Do not edit \`${CONFIG_FILE}\`, \`${PLAN_FILE}\` or this file.`,
+    ])}
+
+## Report format
+
+When finished, report:
+
+${bullet([
+        "Every file you changed and what changed in it.",
+        "The final list of content ids and where each is rendered.",
+        "Ids you renamed from the proposals, with the new names.",
+        "Strings you left unmigrated and why.",
+        "The exact output of `npx @getrefino/cli verify` and of each verification command.",
+        "Anything in these instructions that did not match the repository.",
+    ])}
+`);
+    return sections.join("\n\n");
+}
+export { INSTRUCTIONS_FILE };

package/dist/apply.d.ts

@@ -0,0 +1,23 @@
+import type { ApplyResult, MigrationPlan } from "./types.js";
+export interface ApplyOptions {
+    readonly dryRun?: boolean;
+    /** Version range written for the @getrefino packages. */
+    readonly packageVersion?: string;
+}
+export interface RefinoConfig {
+    readonly version: 1;
+    readonly contentFile: string;
+    /** File serving /api/copy; in hosted mode the Refino copy API URL. */
+    readonly endpoint: string;
+    /** File serving /api/edit-session (probe, login, logout); in hosted mode the Refino token exchange URL. */
+    readonly sessionEndpoint?: string;
+    /** Present when the site is connected to Refino (hosted mode). Public values. */
+    readonly refino?: {
+        readonly siteId: string;
+        readonly appUrl: string;
+    };
+    readonly framework: string;
+    readonly router: string;
+    readonly routes: readonly string[];
+}
+export declare function applyPlan(appDir: string, plan: MigrationPlan, options?: ApplyOptions): ApplyResult;

package/dist/apply.js

@@ -0,0 +1,142 @@
+/**
+ * Safe automatic changes. Everything here is additive and deterministic:
+ * new files are written only if absent, the copy file is merged (existing
+ * values never change), package.json gains dependencies, .env.example
+ * gains a documented block. No JSX is rewritten.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseCopy, serializeCopy } from "@getrefino/core";
+import { renderAgentInstructions } from "./agent.js";
+import { exists, readJson, readText } from "./fs.js";
+import { packageManagerInstall } from "./inspect.js";
+import { CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE, dependencyRange, planContent } from "./plan.js";
+import { ENV_EXAMPLE_BLOCK, boilerplateFiles } from "./templates.js";
+function writeFile(root, relativePath, content, dryRun) {
+    if (dryRun)
+        return;
+    const absolute = join(root, relativePath);
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, content, "utf8");
+}
+export function applyPlan(appDir, plan, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const written = [];
+    const skipped = [];
+    const version = options.packageVersion ?? dependencyRange();
+    // 1. Plan + instructions (always rewritten: they describe this run).
+    writeFile(appDir, PLAN_FILE, `${JSON.stringify(plan, null, 2)}\n`, dryRun);
+    written.push({ path: PLAN_FILE, action: "create", description: "Machine-readable migration plan." });
+    writeFile(appDir, INSTRUCTIONS_FILE, renderAgentInstructions(plan), dryRun);
+    written.push({ path: INSTRUCTIONS_FILE, action: "create", description: "Repository-specific agent instructions." });
+    // 2. Canonical copy file: create, or merge missing keys only.
+    const contentPath = join(appDir, plan.contentFile.path);
+    const selected = planContent(plan);
+    if (exists(contentPath)) {
+        const existingText = readText(contentPath) ?? "{}";
+        let existing;
+        try {
+            existing = { ...parseCopy(existingText) };
+        }
+        catch (error) {
+            skipped.push({ path: plan.contentFile.path, reason: `Existing copy file is invalid: ${error.message}` });
+            existing = {};
+        }
+        const added = Object.keys(selected).filter((id) => !(id in existing));
+        if (added.length > 0 && Object.keys(existing).length > 0) {
+            const merged = { ...existing };
+            for (const id of added)
+                merged[id] = selected[id];
+            writeFile(appDir, plan.contentFile.path, serializeCopy(merged), dryRun);
+            written.push({ path: plan.contentFile.path, action: "merge", description: `Added ${added.length} id(s); existing values untouched.` });
+        }
+        else if (added.length === 0) {
+            skipped.push({ path: plan.contentFile.path, reason: "Already contains every selected id." });
+        }
+    }
+    else {
+        writeFile(appDir, plan.contentFile.path, serializeCopy(selected), dryRun);
+        written.push({ path: plan.contentFile.path, action: "create", description: `${Object.keys(selected).length} selected string(s).` });
+    }
+    // 3. Config file for verify.
+    const config = {
+        version: 1,
+        contentFile: plan.contentFile.path,
+        endpoint: plan.integration.endpoint.path,
+        sessionEndpoint: plan.integration.host.sessionEndpoint,
+        ...(plan.refino ? { refino: plan.refino } : {}),
+        framework: plan.repository.framework,
+        router: plan.repository.router,
+        routes: plan.scope.routes,
+    };
+    const existingConfig = readJson(join(appDir, CONFIG_FILE));
+    if (!existingConfig) {
+        writeFile(appDir, CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, dryRun);
+        written.push({ path: CONFIG_FILE, action: "create", description: "Locations for refino verify." });
+    }
+    else {
+        const routes = [...new Set([...(existingConfig.routes ?? []), ...config.routes])];
+        const merged = { ...config, ...existingConfig, routes };
+        if (JSON.stringify(merged) !== JSON.stringify(existingConfig)) {
+            writeFile(appDir, CONFIG_FILE, `${JSON.stringify(merged, null, 2)}\n`, dryRun);
+            written.push({ path: CONFIG_FILE, action: "modify", description: "Recorded the routes selected in this run." });
+        }
+        else {
+            skipped.push({ path: CONFIG_FILE, reason: "Up to date." });
+        }
+    }
+    // 4. package.json dependencies.
+    const packageJsonPath = join(appDir, "package.json");
+    const pkg = readJson(packageJsonPath);
+    let installCommand = null;
+    if (pkg) {
+        const dependencies = { ...(pkg.dependencies ?? {}) };
+        const wanted = plan.refino ? ["@getrefino/core", "@getrefino/react"] : ["@getrefino/core", "@getrefino/react", "@getrefino/github"];
+        const missing = wanted.filter((name) => !dependencies[name]);
+        if (missing.length > 0) {
+            for (const name of missing)
+                dependencies[name] = version;
+            const ordered = Object.fromEntries(Object.keys(dependencies).sort().map((key) => [key, dependencies[key]]));
+            const text = readText(packageJsonPath) ?? "";
+            const indent = text.match(/^(\s+)"/m)?.[1] ?? "  ";
+            const next = { ...pkg, dependencies: ordered };
+            writeFile(appDir, "package.json", `${JSON.stringify(next, null, indent)}\n`, dryRun);
+            written.push({ path: "package.json", action: "modify", description: `Added ${missing.join(", ")}.` });
+            installCommand = packageManagerInstall(plan.repository.packageManager);
+        }
+        else {
+            skipped.push({ path: "package.json", reason: "Refino packages already listed." });
+        }
+    }
+    else {
+        skipped.push({ path: "package.json", reason: "Not found or not valid JSON." });
+    }
+    // 5. .env.example block (self-hosted only: a hosted site has no variables to document).
+    const envPath = join(appDir, ".env.example");
+    const envText = readText(envPath);
+    const envBlock = ENV_EXAMPLE_BLOCK.replace("COPY_FILE_PATH=", `COPY_FILE_PATH=${plan.repository.appRoot === "." ? plan.contentFile.path : `${plan.repository.appRoot}/${plan.contentFile.path}`}`);
+    if (plan.refino) {
+        // Nothing to document.
+    }
+    else if (envText === null) {
+        writeFile(appDir, ".env.example", `${envBlock.trimStart()}`, dryRun);
+        written.push({ path: ".env.example", action: "create", description: "Documented editor and persistence variables." });
+    }
+    else if (!envText.includes("COPY_GITHUB_TOKEN")) {
+        writeFile(appDir, ".env.example", `${envText.replace(/\s*$/, "\n")}${envBlock}`, dryRun);
+        written.push({ path: ".env.example", action: "append", description: "Appended Refino variables." });
+    }
+    else {
+        skipped.push({ path: ".env.example", reason: "Already documents Refino variables." });
+    }
+    // 6. Boilerplate: only files that do not exist.
+    for (const file of boilerplateFiles(plan)) {
+        if (exists(join(appDir, file.path))) {
+            skipped.push({ path: file.path, reason: "Exists; not overwritten." });
+            continue;
+        }
+        writeFile(appDir, file.path, file.content, dryRun);
+        written.push({ path: file.path, action: "create", description: "Generated boilerplate." });
+    }
+    return { dryRun, written, skipped, installCommand };
+}

package/dist/dataflow.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Static data flow from a string literal to the screen.
+ *
+ * The scanner only reports a string when there is evidence in the source
+ * that it reaches a reader. Beyond literal JSX text that means following a
+ * few well-defined shapes: a constant interpolated into JSX, an array the
+ * file maps into elements, a record indexed then mapped, a prop a component
+ * renders, a default for such a prop, a conditional between two literals,
+ * and a state value a handler sets to a literal. Everything here is
+ * syntactic; nothing is executed and no type checker is used.
+ *
+ * The rule that keeps this conservative: start from a *render sink* (a JSX
+ * expression child, or a prop a component renders) and walk backwards to
+ * literals. Never start from a constant and guess that it might be shown.
+ */
+import ts from "typescript";
+import type { PathAliases } from "./graph.js";
+/** What a component does with a prop it receives. */
+export type PropRole = 
+/** Rendered as a JSX child: `<p>{feature}</p>`. */
+"text"
+/** Mapped into elements whose text is the item: `items.map((i) => <li>{i}</li>)`. */
+ | "list";
+export interface PropRenderInfo {
+    readonly role: PropRole;
+    /** Literal default from the destructuring pattern, when the prop has one. */
+    readonly defaultText: string | null;
+    /** Where the default is written, for reporting. */
+    readonly defaultNode: ts.Node | null;
+}
+export interface ComponentRenderInfo {
+    /** Props the component renders as visible text, by prop name. */
+    readonly props: ReadonlyMap<string, PropRenderInfo>;
+    readonly sourceFile: ts.SourceFile;
+    /** Repository-relative file that defines the component. */
+    readonly file: string;
+}
+export interface DataflowContext {
+    readonly appDir: string;
+    readonly aliases: PathAliases;
+    /** Component render maps, keyed by `file#Component`. */
+    readonly components: Map<string, ComponentRenderInfo | null>;
+}
+export declare function createDataflowContext(appDir: string, aliases: PathAliases): DataflowContext;
+export declare function unwrap(expression: ts.Expression): ts.Expression;
+export declare function literalText(expression: ts.Expression | undefined): string | null;
+/** Function-like nodes that can be a component body. */
+type FunctionLike = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/** Which props of a component in this module render as visible text. */
+export declare function componentRenderInfo(sourceFile: ts.SourceFile, file: string, name: string): ComponentRenderInfo | null;
+/** Where a JSX tag used in `sourceFile` is defined, following one local import. */
+export declare function resolveComponent(context: DataflowContext, sourceFile: ts.SourceFile, absoluteFile: string, tag: string): ComponentRenderInfo | null;
+export interface ResolvedString {
+    readonly text: string;
+    /** Node to report the position of (the literal itself). */
+    readonly node: ts.Node;
+    readonly sourceFile: ts.SourceFile;
+    /** Repository-relative file holding the literal. */
+    readonly file: string;
+    /** Variable, prop or record name the value came from. */
+    readonly collection: string | null;
+    /** A stable, non-text key for the value when the source provides one. */
+    readonly itemKey: string | null;
+    /** Position within an array, when that is the only distinguishing feature. */
+    readonly index: number | null;
+    /** Object field the value was written under. */
+    readonly fieldKey: string | null;
+    /** Sentence fragment explaining how the value reaches the screen. */
+    readonly why: string;
+    /** True when a human should confirm the id or the inclusion. */
+    readonly ambiguous: boolean;
+}
+/** The nearest enclosing function, else the source file. */
+export declare function enclosingScope(node: ts.Node): ts.Node;
+/** Find `const NAME = …` visible from `node`, searching inner scopes first. */
+export declare function findBinding(node: ts.Node, name: string): ts.VariableDeclaration | null;
+/** Elements of an array literal that are all plain string literals. */
+export declare function arrayOfStrings(expression: ts.Expression | undefined): ts.Expression[] | null;
+/** An object literal whose every value is an array of strings, keyed by property name. */
+export declare function recordOfStringArrays(expression: ts.Expression | undefined): Map<string, ts.Expression[]> | null;
+/**
+ * Literals a `useState` value can hold: its initializer and every literal
+ * passed to its setter. Only recognised for the exact
+ * `const [value, setValue] = useState(...)` shape.
+ */
+export declare function stateLiterals(scope: ts.Node, name: string): ts.Expression[] | null;
+/** The callback of `<target>.map(cb)`, when the call maps `target`. */
+export declare function mapCallbackOf(node: ts.Node): {
+    target: ts.Expression;
+    callback: FunctionLike;
+} | null;
+/** Does this callback render its first parameter directly as visible text? */
+export declare function callbackRendersItem(callback: FunctionLike): boolean;
+/** The object-literal field an identifier in a map callback refers to (`item.answer`). */
+export declare function fieldNameOf(expression: ts.Expression, paramName: string | null, destructured: ReadonlySet<string>): string | null;
+export {};