@mapled/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,13 @@
 # @mapled/cli
 
-The `mapled` command line for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Sign in to a project, link the repository to it, generate TypeScript types for the content your site reads, and check the whole integration in one go.
+The `mapled` command line for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Sign in to a project, link the repository to it, generate TypeScript types for the content your site reads, keep a pin of the schema and a manifest of where the code reads it, and check the whole integration in one go.
 
 ```bash
 npx @mapled/cli auth login
 npx @mapled/cli project link
 npx @mapled/cli types generate
+npx @mapled/cli scan --write
+npx @mapled/cli bindings push
 npx @mapled/cli doctor
 ```
 
@@ -45,18 +47,82 @@ Only public values live here — the project id, where the generated types go, t
 npx @mapled/cli types generate
 ```
 
-Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, and doc comments with the field types. Sensitive fields never reach the site and are left out.
+Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, a `MapledSchema` that ties them together, and doc comments with the field types. Sensitive fields never reach the site and are left out.
 
 ```ts
-import type { Article, MapledCollections } from "./mapled-types";
+import type { MapledSchema } from "./mapled-types";
 import { createClient } from "@mapled/next";
 
-const mapled = createClient({ key: process.env.MAPLED_KEY! });
-const { records } = await mapled.getRecords<Article>("articles");
-const home = await mapled.getSingle<MapledCollections["homepage"]>("homepage");
+const mapled = createClient<MapledSchema>({ key: process.env.MAPLED_KEY! });
+const { records } = await mapled.getRecords("articles"); // records[0].data is an Article
+const home = await mapled.getSingle("homepage");          // Homepage | null
 ```
 
-The file names the schema it came from; `mapled doctor` tells you when it is out of date. Run `types generate` again after the schema changes.
+The file names the schema it came from; `mapled doctor` tells you when it is out of date. Run `types generate` again after the schema changes — it refreshes `mapled/schema.json` too when you keep one.
+
+## Pin the schema and see what changed
+
+```bash
+npx @mapled/cli schema pull
+npx @mapled/cli schema diff
+```
+
+`schema pull` writes `mapled/schema.json` — the schema this site is built against, without ids or timestamps, so it diffs cleanly in git. Commit it. When editors or agents change the structure in Mapled, `schema diff` compares the pin with the live schema and judges every change **for a site that reads the content**:
+
+```text
+Schema changes since mapled/schema.json (3f9a1c2b4d5e → 8c1d2e3f4a5b):
+
+Articles (articles)
+  + subtitle   added — short text, optional                     safe
+  - legacy-id  removed — number                                 breaking
+  ~ author     short text → relation to Authors                 breaking
+  ~ title      required → optional (may be empty now)           breaking
+  ~ tags       option “Legacy” removed                          breaking
++ Authors (authors)  new collection — 3 fields                  safe
+
+4 breaking changes, 2 safe changes, judged for a site that reads the content. Update the site where needed, then run `mapled types generate` (it refreshes mapled/schema.json as well).
+```
+
+Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+
+## Scan the code into a manifest
+
+```bash
+npx @mapled/cli scan
+npx @mapled/cli scan --write
+```
+
+The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix) and one binding per place a collection or field is used.
+
+```text
+Scanned 42 files with TypeScript — 3 pages, 14 bindings.
+
+/              app/page.tsx
+  homepage     headline, cover, alt
+  articles     list • title, date, slug
+/blog/[slug]   app/blog/[slug]/page.tsx
+  articles     by slug • title, body
+
+No mapled/manifest.json yet — run `mapled scan --write` to create it, then `mapled bindings push`.
+```
+
+It follows `getRecords` / `getRecord` / `getRecordBySlug` / `getSingle` calls through variables, destructuring, `.map()` callbacks and into the components a record is passed to as a prop, and through helpers in `lib/` that return a read. The parser is your repository's own TypeScript; without it the scanner still finds the collections, but not the fields. Source code never leaves your machine — only the manifest does, when you push it.
+
+`--write` creates or updates `mapled/manifest.json`. Bindings the scan can't see (written by your AI agent, or by hand) are kept and listed; `--prune` drops them. Commit the file.
+
+## Validate and push the manifest
+
+```bash
+npx @mapled/cli manifest validate
+npx @mapled/cli bindings push
+npx @mapled/cli bindings pull
+```
+
+`manifest validate` checks `mapled/manifest.json` the way Mapled will: the shape and limits, duplicate keys, and — against the schema pin or the live schema — collections and fields that don't exist and targets that don't fit the field type, plus files the repository doesn't have. Problems exit 1; warnings only tell you what Mapled would grade down.
+
+`bindings push` sends the manifest to Mapled (the same call your AI agent's `push_site_manifest` makes). Mapled grades every binding — healthy, type mismatch, outdated, missing on site — and the result shows up in **Structure → Bindings**. `--dry-run` validates and stops. Pushing bindings changes structure, so it needs the builder plan.
+
+`bindings pull` writes the pushed manifest into `mapled/manifest.json` — say, after your agent pushed one from a chat and you want the repository's copy. It refuses to overwrite a local file that differs unless you pass `--force`.
 
 ## Check the integration
 
@@ -70,21 +136,23 @@ Mapled doctor — Dolphin Landing
 ✓ Project link         mapled.json → Dolphin Landing
 ✓ Signed in            Mapled CLI • Dolphin Landing
 ✓ Generated types      mapled-types.ts matches the schema (3f9a1c2b4d5e)
+✓ Schema pin           mapled/schema.json matches the schema (3f9a1c2b4d5e)
+✓ Site manifest        mapled/manifest.json is pushed as manifest v3 (14 bindings on 3 pages)
 ✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
 ✓ Secrets in git       No env files or Mapled secrets are tracked.
-✓ @mapled/next         0.3.0 (current)
-✓ mapled CLI           0.1.0 (current)
+✓ @mapled/next         0.6.0 (current)
+✓ mapled CLI           0.2.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
 ✓ Site reads content   Last read 3m ago
 ✓ Publish webhook      Delivered 2h ago to dolphin-landing.example
 ✓ Preview on the site  Responds at https://dolphin-landing.example/api/mapled/preview
-✓ Bindings             12 healthy • synced 2d ago from Claude Code
+✓ Bindings             14 healthy • synced 2d ago from Mapled CLI
 
 1 warning.
 ```
 
-The repository side: the link, the sign-in, the generated types, `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
+The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
 
 Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
 
@@ -92,4 +160,16 @@ Exit code 1 when something is marked ✗; `--json` prints the checks for scripts
 
 - `--api <origin>` — a Mapled API other than `https://api.mapled.io` (or set `MAPLED_API_URL`); `project link` remembers it in `mapled.json`
 - `--no-browser` — print the sign-in link instead of opening a browser
+- `--json` — machine-readable output (`doctor`, `schema diff`, `scan`, `manifest validate`)
 - `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)
+
+## Files in the repository
+
+| File | Written by | Purpose |
+|---|---|---|
+| `mapled.json` | `project link` | The project id, the types path, the framework — public values only |
+| `mapled-types.ts` | `types generate` | TypeScript types of the published content, with `MapledSchema` |
+| `mapled/schema.json` | `schema pull`, `types generate` | The schema this site is built against — `schema diff` starts from it |
+| `mapled/manifest.json` | `scan --write`, `bindings pull`, your agent | Pages and bindings — where the code reads each collection and field |
+
+Commit all four. Credentials never live in the repository.

package/dist/api.d.ts

@@ -6,6 +6,8 @@ export declare class ApiError extends Error {
     code: string | null;
     constructor(status: number, code: string | null, message: string);
 }
+export type Method = "GET" | "POST" | "PATCH" | "DELETE";
+export declare function apiRequest<T>(api: string, method: Method, path: string, token: string, body: unknown, f: Fetch): Promise<T>;
 export declare function apiGet<T>(api: string, path: string, token: string, f: Fetch): Promise<T>;
 /** A signed-in connection with its store: reads refresh the access
     token when it is about to expire or when the API says it did, and
@@ -17,5 +19,7 @@ export declare class Session {
     private readonly f;
     constructor(store: CredentialsFile, file: string, conn: Connection, f: Fetch);
     get<T>(path: string): Promise<T>;
+    send<T>(method: Method, path: string, body: unknown): Promise<T>;
+    private request;
     private refresh;
 }

package/dist/api.js

@@ -12,10 +12,18 @@ export class ApiError extends Error {
         this.code = code;
     }
 }
-export async function apiGet(api, path, token, f) {
+export async function apiRequest(api, method, path, token, body, f) {
     let res;
     try {
-        res = await f(`${api}${path}`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
+        res = await f(`${api}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
     }
     catch {
         throw new CliError(`Couldn't reach ${api}. Check your connection and try again.`);
@@ -26,6 +34,9 @@ export async function apiGet(api, path, token, f) {
     }
     return data;
 }
+export function apiGet(api, path, token, f) {
+    return apiRequest(api, "GET", path, token, undefined, f);
+}
 /** A signed-in connection with its store: reads refresh the access
     token when it is about to expire or when the API says it did, and
     the rotated pair is written back before the call returns. */
@@ -40,17 +51,23 @@ export class Session {
         this.conn = conn;
         this.f = f;
     }
-    async get(path) {
+    get(path) {
+        return this.request("GET", path);
+    }
+    send(method, path, body) {
+        return this.request(method, path, body);
+    }
+    async request(method, path, body) {
         if (new Date(this.conn.expiresAt).getTime() - Date.now() < 60_000)
             await this.refresh();
         try {
-            return await apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+            return await apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
         }
         catch (err) {
             if (err instanceof ApiError && err.status === 401) {
                 if (err.code === "TOKEN_EXPIRED") {
                     await this.refresh();
-                    return apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+                    return apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
                 }
                 throw new CliError(`The connection to ${this.conn.projectName} was revoked. Run \`mapled auth login\` to sign in again.`);
             }

package/dist/commands.d.ts

@@ -2,9 +2,9 @@ import { type ParsedArgs } from "./args.js";
 import { type FoundConfig } from "./config.js";
 import { type Connection } from "./credentials.js";
 import { type Fetch } from "./oauth.js";
-/** The four wave-1 commands (§31) plus sign-out. Everything that talks
-    to the world comes in through `Ctx`, so the commands run in tests
-    against a fake API and a temp directory. */
+/** The commands of waves 1 and 2 (§31). Everything that talks to the
+    world comes in through `Ctx`, so the commands run in tests against a
+    fake API and a temp directory. */
 export type Ctx = {
     cwd: string;
     env: NodeJS.ProcessEnv;
@@ -23,5 +23,11 @@ export declare function login(ctx: Ctx, flags: Flags): Promise<Connection>;
 export declare function logout(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function link(ctx: Ctx, flags: Flags): Promise<FoundConfig>;
 export declare function generate(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function schemaPull(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function schemaDiff(ctx: Ctx, flags: Flags): Promise<number>;
+export declare function manifestValidate(ctx: Ctx, flags: Flags): Promise<number>;
+export declare function bindingsPush(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function bindingsPull(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function scan(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function doctor(ctx: Ctx, flags: Flags): Promise<number>;
 export {};

package/dist/commands.js

@@ -1,17 +1,17 @@
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { apiGet, Session } from "./api.js";
+import { ApiError, apiGet, Session } from "./api.js";
 import { stringFlag } from "./args.js";
 import { CONFIG_FILE, DEFAULT_TYPES_PATH, findConfig, resolveApi, writeConfig } from "./config.js";
 import { connectionsFor, findConnection, readCredentials, removeConnection, upsertConnection, writeCredentials, } from "./credentials.js";
 import * as dr from "./doctor.js";
 import { CliError } from "./errors.js";
+import { checkManifest, compareManifests, fileExistsIn, MANIFEST_FILE, manifestSummary, orderManifest, parseManifest, plural, readManifestFile, writeManifestFile, } from "./manifest.js";
 import { authorize, clientKnown, exchangeCode, registerClient, revokeToken } from "./oauth.js";
-import { formatChecks, summarize, useColor } from "./output.js";
+import { formatChecks, GLYPH, paint, summarize, useColor } from "./output.js";
+import { diffSchema, formatChanges, pinSchema, readPin, SCHEMA_FILE, summarizeChanges, writePin } from "./pin.js";
+import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { generateTypes } from "./types.js";
-function plural(n, word) {
-    return `${n} ${word}${n === 1 ? "" : "s"}`;
-}
 /** The OAuth client id for this API — registered once per machine, and
     again when the server no longer knows it. */
 async function ensureClient(store, api, f) {
@@ -147,6 +147,328 @@ export async function generate(ctx, flags) {
     await writeFile(file, generated.text);
     ctx.out(`Wrote ${path.relative(ctx.cwd, file) || out} — ${plural(generated.collections, "collection")}, ` +
         `${plural(generated.singles, "single")} (schema ${generated.hash}).`);
+    // the pin moves with the types, so `schema diff` starts from what the site was built against
+    const existing = await readPin(found.dir);
+    if (existing && existing.pin.hash !== generated.hash) {
+        await writePin(found.dir, pinSchema(schema, found.config.project));
+        ctx.out(`Refreshed ${SCHEMA_FILE} (schema ${existing.pin.hash} → ${generated.hash}).`);
+    }
+}
+/* ---- wave 2: the schema pin ---- */
+function paintSeverity(color) {
+    return (severity, text) => paint(severity === "breaking" ? "failed" : "skipped", text, color);
+}
+export async function schemaPull(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const live = await session.get("/v1/agent/schema");
+    const pin = pinSchema(live, found.config.project);
+    const existing = await readPin(found.dir);
+    const collections = pin.collections.filter((c) => c.kind === "collection").length;
+    const singles = pin.collections.length - collections;
+    if (!existing) {
+        await writePin(found.dir, pin);
+        ctx.out(`Wrote ${SCHEMA_FILE} — ${plural(collections, "collection")}, ${plural(singles, "single")} (schema ${pin.hash}).`);
+        return;
+    }
+    if (existing.pin.hash === pin.hash) {
+        ctx.out(`${SCHEMA_FILE} is up to date (schema ${pin.hash}).`);
+        return;
+    }
+    const changes = diffSchema(existing.pin.collections, pin.collections);
+    await writePin(found.dir, pin);
+    ctx.out(`Updated ${SCHEMA_FILE} (schema ${existing.pin.hash} → ${pin.hash}): ${summarizeChanges(changes).toLowerCase()}.`);
+    ctx.out("");
+    for (const line of formatChanges(changes, paintSeverity(useColor(ctx.env))))
+        ctx.out(line);
+    const typesPath = found.config.types ?? DEFAULT_TYPES_PATH;
+    const types = await readFile(path.join(found.dir, typesPath), "utf8").catch(() => null);
+    if (types !== null) {
+        ctx.out("");
+        ctx.out(`Next: \`mapled types generate\` — ${typesPath} still describes the previous schema.`);
+    }
+}
+export async function schemaDiff(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const existing = await readPin(found.dir);
+    if (!existing) {
+        throw new CliError(`No ${SCHEMA_FILE} yet. Run \`mapled schema pull\` to record the schema this site is built against.`);
+    }
+    const live = pinSchema(await session.get("/v1/agent/schema"), found.config.project);
+    const changes = diffSchema(existing.pin.collections, live.collections);
+    if (flags.json) {
+        ctx.out(JSON.stringify({ from: existing.pin.hash, to: live.hash, changes }, null, 2));
+    }
+    else if (changes.length === 0) {
+        ctx.out(`No schema changes since ${SCHEMA_FILE} (${existing.pin.hash}).`);
+    }
+    else {
+        ctx.out(`Schema changes since ${SCHEMA_FILE} (${existing.pin.hash} → ${live.hash}):`);
+        ctx.out("");
+        for (const line of formatChanges(changes, paintSeverity(useColor(ctx.env))))
+            ctx.out(line);
+        ctx.out("");
+        const typesPath = found.config.types ?? DEFAULT_TYPES_PATH;
+        const types = await readFile(path.join(found.dir, typesPath), "utf8").catch(() => null);
+        const next = types !== null ? `\`mapled types generate\` (it refreshes ${SCHEMA_FILE} as well)` : `\`mapled schema pull\``;
+        ctx.out(`${summarizeChanges(changes)}, judged for a site that reads the content. Update the site where needed, then run ${next}.`);
+    }
+    return flags["exit-code"] && changes.length > 0 ? 1 : 0;
+}
+async function loadManifest(dir) {
+    const found = await readManifestFile(dir);
+    if (!found)
+        return null;
+    const parsed = parseManifest(found.raw, MANIFEST_FILE);
+    return { file: found.file, ...parsed };
+}
+/** The schema to check bindings against: the pin when the repository
+    keeps one, otherwise the live schema of a signed-in project. */
+async function schemaForChecks(ctx, flags, found) {
+    const pin = await readPin(found.dir);
+    if (pin)
+        return { schema: { collections: pin.pin.collections }, note: null };
+    try {
+        const { session } = await openSession(ctx, flags);
+        return { schema: await session.get("/v1/agent/schema"), note: null };
+    }
+    catch (err) {
+        return {
+            schema: null,
+            note: `Bindings weren't checked against the schema — ${err instanceof Error ? err.message.replace(/\.$/, "") : "sign in"}, or run \`mapled schema pull\`.`,
+        };
+    }
+}
+function formatProblems(problems, color) {
+    return problems.map((p) => `${paint(p.level === "error" ? "failed" : "warning", GLYPH[p.level === "error" ? "failed" : "warning"], color)} ${p.message}`);
+}
+function problemSummary(problems) {
+    const errors = problems.filter((p) => p.level === "error").length;
+    const warnings = problems.length - errors;
+    const parts = [];
+    if (errors > 0)
+        parts.push(plural(errors, "problem"));
+    if (warnings > 0)
+        parts.push(plural(warnings, "warning"));
+    return { errors, warnings, text: parts.join(", ") };
+}
+export async function manifestValidate(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    const dir = found?.dir ?? path.resolve(ctx.cwd);
+    const loaded = await loadManifest(dir);
+    if (!loaded) {
+        throw new CliError(`No ${MANIFEST_FILE} here. Run \`mapled scan --write\` to create one from the site's code, or ask your AI agent to write it.`);
+    }
+    const notes = [];
+    let schema = null;
+    if (found) {
+        const got = await schemaForChecks(ctx, flags, found);
+        schema = got.schema;
+        if (got.note)
+            notes.push(got.note);
+    }
+    else {
+        notes.push(`Bindings weren't checked against the schema — no ${CONFIG_FILE} here; run \`mapled project link\`.`);
+    }
+    const problems = [...loaded.problems, ...(await checkManifest(loaded.manifest, { schema, fileExists: fileExistsIn(dir) }))];
+    problems.sort((a, b) => (a.level === b.level ? 0 : a.level === "error" ? -1 : 1));
+    const summary = problemSummary(problems);
+    if (flags.json) {
+        ctx.out(JSON.stringify({ file: MANIFEST_FILE, bindings: loaded.manifest.bindings.length, pages: loaded.manifest.pages?.length ?? 0, problems, notes }, null, 2));
+    }
+    else {
+        if (problems.length > 0) {
+            for (const line of formatProblems(problems, useColor(ctx.env)))
+                ctx.out(line);
+            ctx.out("");
+        }
+        for (const note of notes)
+            ctx.out(note);
+        ctx.out(`${MANIFEST_FILE}: ${manifestSummary(loaded.manifest)} — ${problems.length === 0 ? "valid" : summary.text}.`);
+        if (summary.errors > 0)
+            ctx.out("Fix the problems before `mapled bindings push`.");
+    }
+    return summary.errors > 0 ? 1 : 0;
+}
+export async function bindingsPush(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const loaded = await loadManifest(found.dir);
+    if (!loaded)
+        throw new CliError(`No ${MANIFEST_FILE} here. Run \`mapled scan --write\` to create one from the site's code.`);
+    const schema = await session.get("/v1/agent/schema");
+    const problems = [...loaded.problems, ...(await checkManifest(loaded.manifest, { schema, fileExists: fileExistsIn(found.dir) }))];
+    const summary = problemSummary(problems);
+    if (summary.errors > 0) {
+        throw new CliError(`${MANIFEST_FILE} has ${plural(summary.errors, "problem")} — run \`mapled manifest validate\` and fix them first.`);
+    }
+    const color = useColor(ctx.env);
+    if (problems.length > 0)
+        for (const line of formatProblems(problems, color))
+            ctx.out(line);
+    const body = orderManifest(loaded.manifest);
+    if (flags["dry-run"]) {
+        ctx.out(`Would push ${MANIFEST_FILE} to ${session.conn.projectName} — ${manifestSummary(body)}${summary.warnings > 0 ? `, ${plural(summary.warnings, "warning")}` : ""}. Nothing was sent.`);
+        return;
+    }
+    let result;
+    try {
+        result = await session.send("POST", "/v1/agent/manifest", body);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === "BUILDER_PLAN_REQUIRED") {
+            throw new CliError("Pushing bindings changes the project's structure, which needs a builder plan — ask the project owner to upgrade.");
+        }
+        throw err;
+    }
+    const s = result.summary;
+    const graded = [`${s.healthy ?? 0} healthy`];
+    if (s.type_mismatch)
+        graded.push(`${s.type_mismatch} type mismatch${s.type_mismatch === 1 ? "" : "es"}`);
+    if (s.outdated)
+        graded.push(`${s.outdated} outdated`);
+    if (s.not_checked)
+        graded.push(`${s.not_checked} not checked`);
+    if (s.missing_on_site)
+        graded.push(`${s.missing_on_site} missing on site`);
+    if (s.disabled)
+        graded.push(`${s.disabled} disabled`);
+    ctx.out(`Pushed ${MANIFEST_FILE} to ${session.conn.projectName} — manifest v${result.manifest.version}, ${plural(body.bindings.length, "binding")}: ${graded.join(", ")}.`);
+    for (const w of result.warnings)
+        ctx.out(`${paint("warning", GLYPH.warning, color)} ${w}`);
+    if ((s.type_mismatch ?? 0) + (s.outdated ?? 0) + (s.missing_on_site ?? 0) > 0 || result.warnings.length > 0) {
+        ctx.out("Open Structure → Bindings in Mapled to review them.");
+    }
+}
+export async function bindingsPull(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    let stored;
+    try {
+        stored = await session.get("/v1/agent/manifest");
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            throw new CliError(`Nothing to pull — no manifest has been pushed to ${session.conn.projectName} yet.`);
+        }
+        throw err;
+    }
+    const local = await loadManifest(found.dir);
+    if (local && !flags.force) {
+        const diff = compareManifests(local.manifest, stored.manifest);
+        if (!diff.same) {
+            const parts = [];
+            if (diff.onlyLocal.length > 0)
+                parts.push(`${diff.onlyLocal.length} not pushed`);
+            if (diff.changed.length > 0)
+                parts.push(`${diff.changed.length} changed`);
+            if (diff.onlyRemote.length > 0)
+                parts.push(`${diff.onlyRemote.length} only in Mapled`);
+            throw new CliError(`${MANIFEST_FILE} differs from the pushed manifest (v${stored.version}): ${parts.join(", ")}. Pass --force to overwrite it, or push yours with \`mapled bindings push\`.`);
+        }
+    }
+    await writeManifestFile(found.dir, stored.manifest);
+    ctx.out(`Wrote ${MANIFEST_FILE} from manifest v${stored.version} (pushed ${dr.ago(stored.createdAt)} by ${stored.clientName}) — ${manifestSummary(stored.manifest)}.`);
+}
+/* ---- wave 2: the scanner ---- */
+function describeScan(result, schema) {
+    const singles = new Set(schema.collections.filter((c) => c.kind === "single").map((c) => c.key));
+    const lines = [];
+    const byPage = new Map();
+    for (const b of result.bindings) {
+        if (!byPage.has(b.page))
+            byPage.set(b.page, []);
+        byPage.get(b.page).push(b);
+    }
+    const fileOf = new Map(result.pages.map((p) => [p.route, p.file ?? ""]));
+    const routeWidth = Math.max(0, ...[...byPage.keys()].map((r) => r.length));
+    for (const [page, list] of byPage) {
+        lines.push(`${page.padEnd(routeWidth)}  ${fileOf.get(page) ?? ""}`.trimEnd());
+        const byCollection = new Map();
+        for (const b of list) {
+            if (!byCollection.has(b.collection))
+                byCollection.set(b.collection, []);
+            byCollection.get(b.collection).push(b);
+        }
+        const width = Math.max(0, ...[...byCollection.keys()].map((c) => c.length));
+        for (const [collection, bindings] of byCollection) {
+            const parts = [];
+            if (bindings.some((b) => b.target === "collection"))
+                parts.push(singles.has(collection) ? "read" : "list");
+            if (bindings.some((b) => b.target === "route_param"))
+                parts.push("by slug");
+            const fields = bindings.filter((b) => b.field && b.target !== "route_param").map((b) => b.field);
+            if (fields.length > 0)
+                parts.push(fields.join(", "));
+            lines.push(`  ${collection.padEnd(width)}  ${parts.join(" • ")}`);
+        }
+    }
+    return lines;
+}
+export async function scan(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    if (!found)
+        throw new CliError(`No ${CONFIG_FILE} here or above. Run \`mapled project link\` first.`);
+    const { schema, note } = await schemaForChecks(ctx, flags, found);
+    if (!schema) {
+        throw new CliError(`The scan needs the schema to name the fields — sign in with \`mapled auth login\` or run \`mapled schema pull\` first.`);
+    }
+    const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
+    const ts = loadTypeScript(found.dir);
+    const result = await scanRepository(found.dir, { framework, schema, ts });
+    const existing = await loadManifest(found.dir);
+    const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
+    if (flags.json) {
+        ctx.out(JSON.stringify({ parser: result.parser, files: result.files, manifest: orderManifest(merged.manifest), notes: result.notes, kept: merged.kept, dropped: merged.dropped }, null, 2));
+        if (flags.write)
+            await writeManifestFile(found.dir, merged.manifest);
+        return;
+    }
+    ctx.out(`Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
+    if (result.bindings.length > 0) {
+        ctx.out("");
+        for (const line of describeScan(result, schema))
+            ctx.out(line);
+    }
+    if (result.notes.length > 0) {
+        ctx.out("");
+        for (const n of result.notes)
+            ctx.out(`${paint("warning", GLYPH.warning, useColor(ctx.env))} ${n}`);
+    }
+    ctx.out("");
+    const keptNote = merged.kept.length > 0 ? ` Kept ${plural(merged.kept.length, "binding")} the scan didn't find (${merged.kept.slice(0, 5).join(", ")}${merged.kept.length > 5 ? ", …" : ""}) — pass --prune to drop them.` : "";
+    const droppedNote = merged.dropped.length > 0 ? ` Dropped ${plural(merged.dropped.length, "binding")} the scan didn't find (${merged.dropped.slice(0, 5).join(", ")}${merged.dropped.length > 5 ? ", …" : ""}).` : "";
+    if (flags.write) {
+        await writeManifestFile(found.dir, merged.manifest);
+        const parts = [];
+        if (merged.added.length > 0)
+            parts.push(`${merged.added.length} new`);
+        if (merged.changed.length > 0)
+            parts.push(`${merged.changed.length} changed`);
+        if (merged.unchanged.length > 0)
+            parts.push(`${merged.unchanged.length} unchanged`);
+        ctx.out(`Wrote ${MANIFEST_FILE} — ${manifestSummary(merged.manifest)}${parts.length > 0 && existing ? ` (${parts.join(", ")})` : ""}.${keptNote}${droppedNote}`);
+        ctx.out("Next: `mapled bindings push`.");
+    }
+    else if (!existing) {
+        ctx.out(`No ${MANIFEST_FILE} yet — run \`mapled scan --write\` to create it, then \`mapled bindings push\`.`);
+    }
+    else {
+        const parts = [];
+        if (merged.added.length > 0)
+            parts.push(`${merged.added.length} new`);
+        if (merged.changed.length > 0)
+            parts.push(`${merged.changed.length} changed`);
+        parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.kept.length > 0)
+            parts.push(`${merged.kept.length} not found in the code (${merged.kept.slice(0, 5).join(", ")}${merged.kept.length > 5 ? ", …" : ""})`);
+        ctx.out(`Compared with ${MANIFEST_FILE}: ${parts.join(", ")}.`);
+        if (merged.added.length > 0 || merged.changed.length > 0) {
+            ctx.out(`Run \`mapled scan --write\` to update ${MANIFEST_FILE}, then \`mapled bindings push\`.`);
+        }
+        else {
+            ctx.out(`${MANIFEST_FILE} already describes what the code reads.`);
+        }
+    }
+    if (note)
+        ctx.out(note);
 }
 export async function doctor(ctx, flags) {
     const found = await findConfig(ctx.cwd);
@@ -173,6 +495,21 @@ export async function doctor(ctx, flags) {
     const typesPath = found?.config.types ?? DEFAULT_TYPES_PATH;
     const existing = await readFile(path.join(dir, typesPath), "utf8").catch(() => null);
     checks.push(dr.checkTypes(existing, schema ? generateTypes(schema, { projectName: status?.project.name }) : null, typesPath));
+    const pin = found ? await readPin(dir).catch(() => null) : null;
+    const livePin = schema && found ? pinSchema(schema, found.config.project) : null;
+    const pinChanges = pin && livePin ? diffSchema(pin.pin.collections, livePin.collections) : null;
+    checks.push(dr.checkSchemaPin(pin?.pin ?? null, livePin?.hash ?? null, pinChanges));
+    const localManifest = await loadManifest(dir).catch(() => null);
+    let remoteManifest = "unknown";
+    if (conn && status && localManifest) {
+        try {
+            remoteManifest = await new Session(store, ctx.credentialsFile, conn, ctx.fetch).get("/v1/agent/manifest");
+        }
+        catch (err) {
+            remoteManifest = err instanceof ApiError && err.status === 404 ? null : "unknown";
+        }
+    }
+    checks.push(dr.checkManifestFile(localManifest ? { manifest: localManifest.manifest, problems: localManifest.problems } : null, remoteManifest));
     checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env));
     checks.push(dr.checkSecrets(await dr.gitFacts(dir)));
     checks.push(dr.checkSdk(await dr.installedVersion(dir, "@mapled/next"), status?.sdk["@mapled/next"]));

package/dist/doctor.d.ts

@@ -1,5 +1,7 @@
 import type { Connection } from "./credentials.js";
+import { type Manifest, type Problem } from "./manifest.js";
 import type { Fetch } from "./oauth.js";
+import { type SchemaChange, type SchemaPin } from "./pin.js";
 import { type Generated } from "./types.js";
 /** `mapled doctor` (§31.3, wave 1): the checks themselves are pure
     functions of what was gathered — the repository side here, the
@@ -103,4 +105,16 @@ export declare function checkPreviewOnSite(origin: string | null, previewPath: s
     status: number | null;
 } | null): Check;
 export declare function checkBindings(bindings: IntegrationStatus["bindings"]): Check;
+export declare function checkSchemaPin(pin: SchemaPin | null, liveHash: string | null, changes: SchemaChange[] | null): Check;
+/** The pushed manifest as `GET /v1/agent/manifest` answers it. */
+export type StoredManifest = {
+    version: number;
+    clientName: string;
+    createdAt: string;
+    manifest: Manifest;
+};
+export declare function checkManifestFile(local: {
+    manifest: Manifest;
+    problems: Problem[];
+} | null, remote: StoredManifest | null | "unknown"): Check;
 export declare const REMOTE_CHECKS: [string, string][];