@@ -29,6 +29,7 @@ import {
   reconcileFloors,
   rootDevDepRowKey,
   scanSkillFences,
+  scopedBuildNotice,
   stripJsonComments,
 } from '../check-skill-examples.mjs';
 import {
@@ -503,6 +504,139 @@ describe('the build filter carries the dependency closure', () => {
   });
 });
 
+/**
+ * The scoping notice under the printed build command — objectui#7811, porting
+ * the shape objectui#7795 landed for `check-doc-snippet-types.mjs`.
+ *
+ * Two precondition paths tell the reader to build and print a command that
+ * builds a CLOSURE rather than the tree, and neither said so. Measured on
+ * `origin/main` `65ce8c576`: `--build-filter` names 10 of the workspace's 40
+ * packages and turbo expands those to 30 in scope, so the reader who ran the
+ * printed command is left looking at 10 packages with no `dist/` and nothing to
+ * tell that apart from a build that half-failed.
+ *
+ * Pinned here is the half that rots unwatched — the notice must keep DERIVING
+ * its numbers and must never grow a package list of its own — plus the half that
+ * would make it worthless: both paths have to actually print it. That it reaches
+ * a real terminal is shown on an unbuilt tree in the pull request; this suite
+ * cannot get there, because those paths only open when this repository's own
+ * packages are unbuilt, and CI has built them by the time it runs.
+ */
+describe('the printed build command says what it does NOT build (objectui#7811)', () => {
+  const SCRIPT = 'scripts/check-skill-examples.mjs';
+  /** A workspace package name, as the notice would spell one if it grew a list. */
+  const PACKAGE_NAME = /@object-ui\//;
+  const sourceOfScript = () => fs.readFileSync(path.join(repoRoot, SCRIPT), 'utf8');
+
+  /**
+   * Every place the gate prints the build command, paired with the slice that
+   * runs from it to the `couldNotRun` exit that site leaves through.
+   *
+   * Anchored on the printed COMMAND rather than on `PRECONDITION NOT MET`: the
+   * empty-marked-population path prints that headline too and correctly prints
+   * no build command, so a scan anchored on the headline would demand a notice
+   * where there is nothing to scope.
+   */
+  const buildCommandSites = (source: string): string[] => {
+    const marker = 'check-skill-examples.mjs --build-filter) --concurrency=2';
+    const slices: string[] = [];
+    for (let at = source.indexOf(marker); at !== -1; at = source.indexOf(marker, at + 1)) {
+      const end = source.indexOf('EXIT_CODES.couldNotRun;', at);
+      expect(end, 'a site that prints the build command must still leave through exit 2').toBeGreaterThan(at);
+      slices.push(source.slice(at, end));
+    }
+    return slices;
+  };
+
+  it('interpolates the counts it is handed — without this, a fixed sentence passes every pin below', () => {
+    expect(scopedBuildNotice(10, 40)).toContain('10 package(s)');
+    expect(scopedBuildNotice(10, 40)).toContain('packages/ holds 40');
+    // The control: different inputs, different text. A hard-coded "10 of 40" —
+    // exactly the rotting summary this notice exists not to be — passes both
+    // assertions above and fails these.
+    const other = scopedBuildNotice(1, 2);
+    expect(other).toContain('1 package(s)');
+    expect(other).toContain('packages/ holds 2');
+    expect(other).not.toContain('10');
+    expect(other).not.toContain('40');
+  });
+
+  it('names no package of its own — the reader is sent to the filter, never to a copy of it', () => {
+    const notice = scopedBuildNotice(10, 40);
+    // The control, and it has to be taken from THIS tree: a matcher that catches
+    // no package name anywhere would satisfy the refusal below while proving
+    // nothing. The names come from the gate's own reading of the workspace,
+    // which is the very set a second copy would be copied from.
+    const named = [...(analyze({}) as unknown as { neededPackages: Set<string> }).neededPackages];
+    expect(
+      named.filter((n) => PACKAGE_NAME.test(n)),
+      'nothing in this tree matches the matcher, so the refusal below is vacuous',
+    ).not.toHaveLength(0);
+    expect(
+      notice,
+      'a package name written here is a second list of what gets built, and it rots the first time the marked population moves',
+    ).not.toMatch(PACKAGE_NAME);
+    expect(notice).toContain('--build-filter');
+    expect(notice, 'without a way to ask, the notice is one more thing the reader has to trust').toContain(
+      '--dry=text',
+    );
+  });
+
+  it('says the build is scoped and that what it leaves behind is the designed end state', () => {
+    const notice = scopedBuildNotice(10, 40);
+    expect(notice).toContain('not a whole-tree build');
+    expect(notice).toContain('left exactly as it was');
+    expect(notice).toContain('designed end state');
+  });
+
+  it('is printed on BOTH precondition paths that print the command, not merely defined', () => {
+    const slices = buildCommandSites(sourceOfScript());
+    expect(
+      slices,
+      'objectui#7811 named two sites — the regular path and the --self-test type-check leg',
+    ).toHaveLength(2);
+    for (const slice of slices) {
+      expect(
+        slice,
+        'a notice nothing calls is a string in a file, and objectui#7811 was filed about a reader who was never told',
+      ).toContain('scopedBuildNotice(');
+    }
+  });
+
+  it('is handed numbers the gate read, never a literal at the call site', () => {
+    for (const slice of buildCommandSites(sourceOfScript())) {
+      const call = slice.slice(slice.indexOf('scopedBuildNotice('));
+      expect(call).toContain('state.neededPackages.size');
+      expect(call).toContain('state.packageDirOf');
+      expect(
+        call,
+        'a number written at the call site is the rotting summary this notice exists not to be',
+      ).not.toMatch(/scopedBuildNotice\(\s*\d/);
+    }
+  });
+
+  it('counts the workspace from what the gate itself read, not from a number written down', () => {
+    const names = withTree(
+      (write) => {
+        write('skills/objectui/guides/sample.md', '# Sample\n');
+        write(
+          'packages/pkg-a/package.json',
+          JSON.stringify({ name: '@fixture/pkg-a', types: './dist/index.d.ts' }),
+        );
+        write(
+          'packages/pkg-b/package.json',
+          JSON.stringify({ name: '@fixture/pkg-b', types: './dist/index.d.ts' }),
+        );
+      },
+      (dir) =>
+        Object.keys(
+          (analyze({ root: dir }) as unknown as { packageDirOf: Record<string, string> }).packageDirOf,
+        ).sort(),
+    );
+    expect(names).toEqual(['@fixture/pkg-a', '@fixture/pkg-b']);
+  });
+});
+
 describe('wiring — the gate is reachable and a markdown-only PR starts it', () => {
   const SCRIPT = 'scripts/check-skill-examples.mjs';
   const workflowDir = path.join(repoRoot, '.github/workflows');
 
@@ -1074,6 +1074,12 @@ export function analyze({ root = repoRoot, measure = false, baseline = KNOWN_BAR
     untypedDependencies,
     declaredSpecifiers,
     neededPackages,
+    // Carried out so the precondition paths can say how much of the workspace
+    // their build filter leaves alone (objectui#7811). It is the map this
+    // function already walked to resolve `neededPackages`, not a second reading
+    // of the tree — the whole point of `scopedBuildNotice` is that its numbers
+    // are DERIVED, so the number it is handed has to come from here.
+    packageDirOf,
   };
 }
 
@@ -1102,6 +1108,50 @@ export function buildFilterArgs(packages) {
     .join(' ');
 }
 
+/**
+ * What that printed build command does NOT do, printed under it — objectui#7811,
+ * porting the shape objectui#7795 landed as `check-doc-snippet-types.mjs`'s
+ * `scopedBuildNotice`.
+ *
+ * Both precondition paths tell the reader to build, and both print a command
+ * that builds a CLOSURE rather than the tree, having said so nowhere. Measured
+ * on `origin/main` `65ce8c576`: `--build-filter` names 10 of the workspace's 40
+ * packages, and expanding each one's dependency closure puts 30 in scope — so
+ * running the printed command exactly as given leaves 10 packages with no
+ * `dist/`, and nothing distinguishes that from a build that half-failed. The
+ * trimming is deliberate (`skill-examples.yml`'s header forbids the unfiltered
+ * build in as many words, under the 2026-08-16 ruling on objectui#4846), so what
+ * was missing is the sentence, never a wider filter.
+ *
+ * Both counts are ARGUMENTS and the text names no package on purpose. A list of
+ * "what gets built" written out here would be a second copy of a set this file
+ * already computes, and it would rot the first time the marked population moved;
+ * the reader who wants the exact set is sent to the same filter, expanded by the
+ * same tool that is about to run it — `--dry=text` makes turbo print a
+ * `Packages in scope` line (and, below it, a table of the same set) instead of
+ * building. `packages/` is the directory `derivePackageTypePaths` walks, which
+ * is where `total` is counted from; it is a location, not a package list.
+ *
+ * `check-skill-examples.test.ts` pins the half that rots unwatched — the numbers
+ * stay derived, no package name grows here — plus the half that would make it
+ * worthless: both precondition paths have to actually print it.
+ *
+ * @param {number} named packages `--build-filter` names (the marked examples' imports)
+ * @param {number} total packages under `packages/` this gate resolves against
+ * @returns {string} one paragraph for a precondition path's stderr
+ */
+export function scopedBuildNotice(named, total) {
+  return (
+    `That build is SCOPED, and it is not a whole-tree build: --build-filter names the ${named} package(s) the ` +
+    `marked examples import (packages/ holds ${total}) plus each one's dependency closure, and every package ` +
+    'outside that closure is left exactly as it was. An unbuilt package still sitting there when the build ' +
+    "finishes is this gate's designed end state, not a build that half-failed — a whole-workspace build for a " +
+    'guide check is what this gate\'s workflow refuses outright. For the exact set, ask that same filter rather ' +
+    'than a list written down somewhere else: append --dry=text to the command above and read its "Packages in ' +
+    'scope" line.'
+  );
+}
+
 // ── Reporting ────────────────────────────────────────────────────────────────
 
 function formatDiagnostic(diagnostic, block) {
@@ -1285,6 +1335,9 @@ function main() {
       '  pnpm exec turbo run build $(node scripts/check-skill-examples.mjs --build-filter) --concurrency=2\n' +
         '  pnpm check:skill-examples',
     );
+    console.error(
+      `\n${scopedBuildNotice(state.neededPackages.size, Object.keys(state.packageDirOf).length)}`,
+    );
     return EXIT_CODES.couldNotRun;
   }
 
@@ -1721,6 +1774,9 @@ export function selfTest() {
       '  pnpm exec turbo run build $(node scripts/check-skill-examples.mjs --build-filter) --concurrency=2\n' +
         '  node scripts/check-skill-examples.mjs --self-test',
     );
+    console.error(
+      `\n${scopedBuildNotice(state.neededPackages.size, Object.keys(state.packageDirOf).length)}`,
+    );
     for (const c of cases.filter((c2) => !c2.ok)) console.error(`  ✗ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
     return EXIT_CODES.couldNotRun;
   }