@caperjs/core 0.5.1 → 0.6.0

package/README.md

@@ -8,7 +8,13 @@ It sits on top of PixiJS — a renderer, not a game engine — and adds the part
 
 ## Status
 
-This package is **not yet published to npm**. The recommended way to use it is to clone the [Caper monorepo](https://github.com/anthonysapp/caper), run the kitchen-sink, and either fork it as a starter or vendor `packages/core` into your own project. First publish lands in Phase 7.
+Published on npm as `@caperjs/core`.
+
+## For AI agents
+
+- `npx caper agent init` installs the `caper` skill + `AGENTS.md` pointers for this project.
+- The reference is `node_modules/@caperjs/core/extras/llms.txt` — read it by section (`grep -n '^## '`), not whole.
+- Engine source ships in the package under `src/`.
 
 ## Highlights
 

package/build/assetpack.mjs

@@ -302,6 +302,12 @@ export function assetpackPlugin(manifestUrl = defaultManifestUrl, pixiPipesConfi
 
   return {
     name: 'vite-plugin-assetpack',
+    api: {
+      runOnce: async () => {
+        await getConfig();
+        await new AssetPack(apConfig).run();
+      },
+    },
     async configResolved(resolvedConfig) {
       mode = resolvedConfig.command;
       // Captured before getConfig() below, which is what consumes it.

package/build/plugins/assetTypes.mjs

@@ -398,8 +398,10 @@ export function assetTypesPlugin(manifestUrl = 'assets.json') {
       }
       const manifest = JSON.parse(await fs.promises.readFile(manifestPath, 'utf8'));
       await writeAssetTypes(manifest, path.dirname(manifestPath), path.join(publicDir, 'assets'), root);
-      logger.info('Caper asset types plugin:: manifest changed, reloading browser...');
-      viteServer?.ws?.send({ type: 'full-reload' });
+      if (viteServer) {
+        logger.info('Caper asset types plugin:: manifest changed, reloading browser...');
+        viteServer.ws.send({ type: 'full-reload' });
+      }
     } catch (error) {
       logger.error('Caper asset types plugin:: Error handling manifest change:', error);
     }
@@ -409,6 +411,9 @@ export function assetTypesPlugin(manifestUrl = 'assets.json') {
 
   return {
     name: 'vite-plugin-asset-types',
+    api: {
+      generateTypes: () => generate(manifestUrl),
+    },
     configResolved(config) {
       publicDir = config.publicDir;
       root = config.root;

package/build/plugins/caperConfig.mjs

@@ -418,6 +418,9 @@ declare module '@caperjs/core' {
 
   return {
     name: 'vite-plugin-caper-config',
+    api: {
+      generateTypes: () => build('Generating types from caper.config.ts'),
+    },
     configResolved(config) {
       publicDir = config.publicDir;
       root = config.root;

package/cli/agent.mjs

@@ -0,0 +1,112 @@
+import { bgRed, bold, cyan, green, white } from 'kleur/colors';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { probe } from './probe.mjs';
+
+/**
+ * `caper agent <subcommand>` — `init` installs the shipped `caper` agent skill
+ * into the current app; `probe` drives a running Caper app through the
+ * Playwright automation bridge.
+ */
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+// `.href` so this also works where the global URL is a DOM polyfill (vitest + happy-dom).
+function resolveModuleRelative(rel) {
+  return fileURLToPath(new URL(rel, import.meta.url).href);
+}
+
+function readVersion() {
+  return JSON.parse(fs.readFileSync(resolveModuleRelative('../package.json'), 'utf-8')).version;
+}
+
+function makeBlock(skillPath, version) {
+  return `${START_MARKER}
+## Caper (engine) — agent pointers
+
+This app runs on the Caper engine (\`@caperjs/core@${version}\`). Generated by \`caper agent init\`; re-run it after upgrading caper. Do not edit between these markers.
+
+- Before engine-facing work (scenes, entities, popups, UI, plugins, \`caper.config.ts\`, assets, generated types), load the \`caper\` skill at \`${skillPath}\`.
+- Read the reference by section, not whole: \`node_modules/@caperjs/core/extras/llms.txt\` (\`grep -n '^## '\` for the outline). Engine source ships at \`node_modules/@caperjs/core/src/\`.
+- Verify: typecheck → build → drive the running app through \`window.Caper\` / \`Caper.automation[appId]\` (llms.txt §17). Never leave a dev server running in the foreground.
+${END_MARKER}`;
+}
+
+function upsertContext(cwd, dir) {
+  const candidates = ['AGENTS.md', 'CLAUDE.md'];
+  let contextFile = candidates.find((name) => fs.existsSync(path.join(cwd, name)));
+
+  if (!contextFile) {
+    contextFile = 'AGENTS.md';
+  }
+
+  const contextPath = path.resolve(cwd, contextFile);
+  const existing = fs.existsSync(contextPath) ? fs.readFileSync(contextPath, 'utf-8') : '';
+  const skillPath = path.posix.join(dir, 'caper/SKILL.md');
+  const version = readVersion();
+  const block = makeBlock(skillPath, version);
+
+  const startIndex = existing.indexOf(START_MARKER);
+  const endIndex = existing.indexOf(END_MARKER);
+
+  let contents;
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex);
+    const after = existing.slice(endIndex + END_MARKER.length);
+    const trimmedBefore = before.replace(/\s+$/, '');
+    const trimmedAfter = after.replace(/^\s+/, '');
+    const spacerBefore = trimmedBefore ? '\n\n' : '';
+    const spacerAfter = trimmedAfter ? '\n\n' : '';
+    contents = `${trimmedBefore}${spacerBefore}${block}${spacerAfter}${trimmedAfter}`;
+  } else if (existing) {
+    const spacer = existing.endsWith('\n\n') ? '' : '\n\n';
+    contents = `${existing.replace(/\s+$/, '')}${spacer}${block}\n`;
+  } else {
+    contents = `${block}\n`;
+  }
+
+  fs.writeFileSync(contextPath, contents, 'utf-8');
+  return contextPath;
+}
+
+export async function agentInit(cwd, { dir = '.claude/skills' } = {}) {
+  const skillSource = resolveModuleRelative('../extras/skills/caper/SKILL.md');
+  const skillDir = path.resolve(cwd, dir, 'caper');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(skillSource, skillFile);
+
+  const contextFile = upsertContext(cwd, dir);
+
+  console.log(green(bold('✓ Created caper skill')) + ` ${cyan(path.relative(cwd, skillFile).replace(/\\/g, '/'))}`);
+  console.log(green(bold('✓ Updated agent context')) + ` ${cyan(path.relative(cwd, contextFile).replace(/\\/g, '/'))}`);
+
+  return { skillFile, contextFile };
+}
+
+export async function agent(args) {
+  if (args[0] === 'init') {
+    let dir = '.claude/skills';
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === '--dir' && args[i + 1]) {
+        dir = args[i + 1];
+        i++;
+      }
+    }
+    await agentInit(process.cwd(), { dir });
+    return;
+  }
+
+  if (args[0] === 'probe') {
+    await probe(args.slice(1));
+    return;
+  }
+
+  const subcommand = args[0] ?? '(none)';
+  console.error(bold(bgRed(white(`Unknown agent command: "${subcommand}". Please use "init" or "probe".`))));
+  process.exit(1);
+}

package/cli/agent.test.mjs

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agentInit } from './agent.mjs';
+
+const shippedSkill = path.resolve(process.cwd(), 'extras/skills/caper/SKILL.md');
+
+const START_MARKER = '<!-- caper:agent-start -->';
+
+let tempDir = null;
+
+afterEach(() => {
+  if (tempDir && fs.existsSync(tempDir)) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+});
+
+function makeTempDir() {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'caper-agent-'));
+  return tempDir;
+}
+
+function countMarkers(contents) {
+  return {
+    start: (contents.match(/<!-- caper:agent-start -->/g) || []).length,
+    end: (contents.match(/<!-- caper:agent-end -->/g) || []).length,
+  };
+}
+
+describe('agentInit', () => {
+  it('creates the default skill copy and AGENTS.md when no context file exists', async () => {
+    const cwd = makeTempDir();
+
+    const { skillFile, contextFile } = await agentInit(cwd);
+
+    expect(fs.existsSync(skillFile)).toBe(true);
+    expect(fs.readFileSync(skillFile, 'utf-8')).toBe(fs.readFileSync(shippedSkill, 'utf-8'));
+    expect(path.basename(contextFile)).toBe('AGENTS.md');
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('<!-- caper:agent-start -->');
+    expect(context).toContain('<!-- caper:agent-end -->');
+    expect(context).toContain('.claude/skills/caper/SKILL.md');
+  });
+
+  it('respects --dir and references the custom skill path', async () => {
+    const cwd = makeTempDir();
+
+    const { skillFile, contextFile } = await agentInit(cwd, { dir: 'skills' });
+
+    expect(skillFile).toBe(path.join(cwd, 'skills/caper/SKILL.md'));
+    expect(fs.existsSync(skillFile)).toBe(true);
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('skills/caper/SKILL.md');
+    expect(context).not.toContain('.claude/skills/caper/SKILL.md');
+  });
+
+  it('appends the block to CLAUDE.md when only CLAUDE.md exists', async () => {
+    const cwd = makeTempDir();
+    const original = '# Project CLAUDE.md\n\nSome existing guidance.\n';
+    fs.writeFileSync(path.join(cwd, 'CLAUDE.md'), original, 'utf-8');
+
+    const { skillFile, contextFile } = await agentInit(cwd);
+
+    expect(path.basename(contextFile)).toBe('CLAUDE.md');
+    expect(fs.existsSync(path.join(cwd, 'AGENTS.md'))).toBe(false);
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('Some existing guidance.');
+    expect(context).toContain('<!-- caper:agent-start -->');
+    expect(context).toContain('<!-- caper:agent-end -->');
+    expect(context.indexOf('Some existing guidance.')).toBeLessThan(context.indexOf(START_MARKER));
+  });
+
+  it('is idempotent and preserves user edits outside the markers', async () => {
+    const cwd = makeTempDir();
+
+    await agentInit(cwd);
+    const first = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf-8');
+
+    // User edits outside the markers
+    const edited = `# App pointers\n\n${first}\n\n## Custom section\n\nKeep me.\n`;
+    fs.writeFileSync(path.join(cwd, 'AGENTS.md'), edited, 'utf-8');
+
+    await agentInit(cwd);
+    const second = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf-8');
+
+    const markers = countMarkers(second);
+    expect(markers.start).toBe(1);
+    expect(markers.end).toBe(1);
+    expect(second).toContain('# App pointers');
+    expect(second).toContain('## Custom section');
+    expect(second).toContain('Keep me.');
+
+    // Replace the block with the freshly generated one so we can compare the rest
+    const start = second.indexOf('<!-- caper:agent-start -->');
+    const end = second.indexOf('<!-- caper:agent-end -->') + '<!-- caper:agent-end -->'.length;
+    const regenerated = second.slice(start, end);
+    expect(regenerated).toBe(first.trimEnd());
+  });
+});

package/cli/create.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { promisify } from 'node:util';
 import shell from 'shelljs';
+import { agentInit } from './agent.mjs';
 import { copy, dist, mkdirp, package_manager } from './utils.mjs';
 
 let packageManager = package_manager;
@@ -150,7 +151,7 @@ export function injectPluginsIntoConfig(configContents, pluginConfigs) {
  * @param {string} cwd
  * @param {string[]} plugins
  */
-function write_template_files(cwd, template, applicationNameForPkg, applicationName, defaultName, plugins) {
+async function write_template_files(cwd, template, applicationNameForPkg, applicationName, defaultName, plugins) {
   const dir = dist(`templates/${template}`);
   copy(`${dir}/package.template.json`, `${cwd}/package.json`);
 
@@ -209,6 +210,14 @@ function write_template_files(cwd, template, applicationNameForPkg, applicationN
   readme_contents = readme_contents.replace(/~PACKAGE_MANAGER~/g, mgr);
   fs.writeFileSync(readme_file, readme_contents, 'utf-8');
 
+  // Install the shipped caper agent skill and upsert pointers into AGENTS.md/CLAUDE.md.
+  // This is best-effort: scaffolding must not fail because the agent init step failed.
+  try {
+    await agentInit(cwd);
+  } catch (e) {
+    console.warn('Warning: failed to install the caper agent skill:', e.message);
+  }
+
   // find __APPLICATION_NAME__.ts and replace it with the application name, then delete ~Application.ts
   const app_file = `${cwd}/src/__APPLICATION_NAME__.ts`;
   const app_contents = fs.readFileSync(app_file, 'utf-8');

package/cli/doctor.mjs

@@ -0,0 +1,193 @@
+import { dim, green, red, yellow } from 'kleur/colors';
+
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `caper doctor` — one-shot health report for a Caper app.
+ *
+ * Answers the recurring agent questions: which caper is active, is it current,
+ * are generated types fresh, and are the agent pointers installed.
+ */
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+const readInstalledVersion = () => {
+  const url = new URL('../package.json', import.meta.url);
+  const pkgPath = url.protocol === 'file:' ? fileURLToPath(url.href) : path.resolve(process.cwd(), 'package.json');
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+};
+
+const rel = (cwd, p) => {
+  const r = path.relative(cwd, p);
+  return r.startsWith('..') ? r : `.${path.sep}${r}`;
+};
+
+const newestMtime = (dirOrFile) => {
+  if (!fs.existsSync(dirOrFile)) return null;
+  const stat = fs.statSync(dirOrFile);
+  if (stat.isFile()) return stat.mtime;
+  if (!stat.isDirectory()) return null;
+  let newest = null;
+  for (const entry of fs.readdirSync(dirOrFile)) {
+    if (entry === 'node_modules' || entry === '.git') continue;
+    const childNewest = newestMtime(path.join(dirOrFile, entry));
+    if (childNewest && (!newest || childNewest > newest)) newest = childNewest;
+  }
+  return newest;
+};
+
+const compareVersions = (a, b) => {
+  const ap = a.split('.').map(Number);
+  const bp = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const av = ap[i] ?? 0;
+    const bv = bp[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+};
+
+const npmLatestVersion = (pkg, timeoutMs = 5000) =>
+  new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), timeoutMs);
+    execFile('npm', ['view', pkg, 'version'], { timeout: timeoutMs }, (err, stdout) => {
+      clearTimeout(timer);
+      resolve(err || !stdout ? null : stdout.trim());
+    });
+  });
+
+const push = (checks, id, status, label, hint) => {
+  checks.push({ id, status, label, ...(hint ? { hint } : {}) });
+};
+
+export async function runChecks(cwd, { online = true } = {}) {
+  const checks = [];
+  const installedVersion = readInstalledVersion();
+  const nodeModulesCaper = path.join(cwd, 'node_modules/@caperjs/core');
+
+  push(checks, 'version', 'ok', `@caperjs/core ${installedVersion}`);
+
+  if (online) {
+    const latest = await npmLatestVersion('@caperjs/core');
+    if (!latest) push(checks, 'npm', 'warn', 'latest on npm', 'lookup failed (offline?)');
+    else if (compareVersions(installedVersion, latest) < 0) {
+      push(checks, 'npm', 'warn', `latest on npm ${latest}`, 'pnpm update @caperjs/core@latest');
+    } else push(checks, 'npm', 'ok', `latest on npm ${latest}`);
+  }
+
+  if (!fs.existsSync(nodeModulesCaper)) {
+    push(checks, 'link', 'fail', '@caperjs/core not in node_modules', 'pnpm install');
+  } else {
+    let real;
+    try {
+      real = fs.realpathSync(nodeModulesCaper);
+    } catch {
+      push(checks, 'link', 'fail', 'node_modules/@caperjs/core is broken', 'pnpm install');
+    }
+    if (real) {
+      if (real.startsWith(path.join(cwd, 'node_modules') + path.sep)) {
+        push(checks, 'link', 'ok', 'registry build');
+      } else {
+        const buildFile = path.join(real, 'lib/caper.mjs');
+        const label = `linked from ${rel(cwd, real)}`;
+        if (!fs.existsSync(buildFile)) {
+          push(checks, 'link', 'fail', label, 'pnpm build in linked package');
+        } else {
+          const srcMtime = newestMtime(path.join(real, 'src'));
+          const stale = srcMtime && srcMtime > fs.statSync(buildFile).mtime;
+          push(checks, 'link', stale ? 'warn' : 'ok', label, stale ? 'engine source edited after last build; run pnpm build there' : undefined);
+        }
+      }
+    }
+  }
+
+  const appTypesFile = path.join(cwd, 'src/types/caper-app.d.ts');
+  if (!fs.existsSync(appTypesFile)) {
+    push(checks, 'app-types', 'fail', 'generated app types missing', 'npx caper types');
+  } else {
+    const sources = ['caper.config.ts', 'src/scenes', 'src/plugins', 'src/popups', 'src/entities', 'src/ui', 'src/locales'].map((s) => path.join(cwd, s));
+    const newestSource = sources.reduce((best, s) => {
+      const m = newestMtime(s);
+      return m && (!best || m > best) ? m : best;
+    }, null);
+    const stale = newestSource && newestSource > fs.statSync(appTypesFile).mtime;
+    push(checks, 'app-types', stale ? 'warn' : 'ok', stale ? 'generated app types stale' : 'generated app types fresh', stale ? 'npx caper types (or restart dev server)' : undefined);
+  }
+
+  const assetTypesFile = path.join(cwd, 'src/types/caper-assets.d.ts');
+  const assetsManifest = path.join(cwd, 'public/assets/assets.json');
+  if (fs.existsSync(assetTypesFile)) push(checks, 'asset-types', 'ok', 'generated asset types present');
+  else push(checks, 'asset-types', 'warn', 'generated asset types missing', 'npx caper types (app may have assets: false)');
+  if (fs.existsSync(assetsManifest)) push(checks, 'asset-manifest', 'ok', 'asset manifest present');
+  else push(checks, 'asset-manifest', 'warn', 'asset manifest missing', 'asset pipeline has not run; npx caper types or pnpm dev once');
+
+  const agentContext = ['AGENTS.md', 'CLAUDE.md'].find((name) => fs.existsSync(path.join(cwd, name)));
+  if (!agentContext) {
+    push(checks, 'agent', 'warn', 'agent context missing', 'npx caper agent init');
+  } else {
+    const contents = fs.readFileSync(path.join(cwd, agentContext), 'utf-8');
+    const start = contents.indexOf(START_MARKER);
+    const end = contents.indexOf(END_MARKER);
+    if (start === -1 || end === -1 || end <= start) {
+      push(checks, 'agent', 'warn', 'agent pointers not installed', 'npx caper agent init');
+    } else {
+      const block = contents.slice(start, end + END_MARKER.length);
+      const versionMatch = block.match(/@caperjs\/core@(\d+\.\d+\.\d+)/);
+      const skillMatch = block.match(/load the `caper` skill at `([^`]+)`/);
+      const hints = [];
+      if (versionMatch && versionMatch[1] !== installedVersion) {
+        hints.push(`pointer is @caperjs/core@${versionMatch[1]}; re-run npx caper agent init`);
+      }
+      if (skillMatch) {
+        if (!fs.existsSync(path.join(cwd, skillMatch[1].replace(/\//g, path.sep)))) {
+          hints.push(`skill file missing at ${skillMatch[1]}; npx caper agent init`);
+        }
+      } else hints.push('skill path not found in pointer block; npx caper agent init');
+      push(checks, 'agent', hints.length ? 'warn' : 'ok', 'agent pointers', hints.length ? hints.join('; ') : undefined);
+    }
+  }
+
+  const peerDeps = ['pixi.js', 'gsap', '@pixi/sound', 'vite'];
+  const required = new Set(['pixi.js', 'vite']);
+  let peerStatus = 'ok';
+  // Direct lookup rather than require.resolve: pixi.js's `exports` map does not
+  // expose ./package.json, so resolve() throws even when it is installed.
+  const peerResults = peerDeps.map((pkg) => {
+    try {
+      const pkgJsonPath = path.join(cwd, 'node_modules', pkg, 'package.json');
+      return `${pkg}@${JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version}`;
+    } catch {
+      if (required.has(pkg)) peerStatus = 'fail';
+      else if (peerStatus === 'ok') peerStatus = 'warn';
+      return `${pkg} missing`;
+    }
+  });
+  push(checks, 'peers', peerStatus, `peer deps: ${peerResults.join(', ')}`, peerStatus !== 'ok' ? 'pnpm install' : undefined);
+
+  const caches = ['.assetpack', '.cache', 'dist'].filter((name) => fs.existsSync(path.join(cwd, name)));
+  push(checks, 'caches', 'ok', `caches${caches.length ? `: ${caches.join(', ')}` : ' clean'}`, caches.length ? 'rm -rf them on weird asset/name mismatches' : undefined);
+
+  return checks;
+}
+
+export async function doctor(args) {
+  const offline = args.includes('--offline');
+  const json = args.includes('--json');
+  const checks = await runChecks(process.cwd(), { online: !offline });
+
+  if (json) {
+    console.log(JSON.stringify(checks, null, 2));
+  } else {
+    for (const check of checks) {
+      const symbol = check.status === 'ok' ? green('✓') : check.status === 'warn' ? yellow('⚠') : red('✗');
+      console.log(`${symbol} ${check.label}${check.hint ? ` ${dim(check.hint)}` : ''}`);
+    }
+  }
+
+  if (checks.some((c) => c.status === 'fail')) process.exit(1);
+}

package/cli/doctor.test.mjs

@@ -0,0 +1,142 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { agentInit } from './agent.mjs';
+import { runChecks } from './doctor.mjs';
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+const installedVersion = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), 'package.json'), 'utf-8')).version;
+
+let tempDir = null;
+
+afterEach(() => {
+  if (tempDir && fs.existsSync(tempDir)) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+});
+
+function makeTempDir() {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'caper-doctor-'));
+  return tempDir;
+}
+
+function setMtime(file, secondsAgo) {
+  const t = Date.now() / 1000 - secondsAgo;
+  fs.utimesSync(file, t, t);
+}
+
+function find(checks, id) {
+  return checks.find((c) => c.id === id);
+}
+
+describe('runChecks', () => {
+  it('reports failures/warnings for an empty app directory', async () => {
+    const cwd = makeTempDir();
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'version').status).toBe('ok');
+    expect(find(checks, 'link').status).toBe('fail');
+    expect(find(checks, 'app-types').status).toBe('fail');
+    expect(find(checks, 'agent').status).toBe('warn');
+    expect(find(checks, 'asset-types').status).toBe('warn');
+    expect(find(checks, 'asset-manifest').status).toBe('warn');
+    expect(find(checks, 'caches').status).toBe('ok');
+  });
+
+  it('marks app types ok when fresh and warns after a newer source file', async () => {
+    const cwd = makeTempDir();
+
+    fs.mkdirSync(path.join(cwd, 'src/types'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, 'caper.config.ts'), '// config', 'utf-8');
+    fs.writeFileSync(path.join(cwd, 'src/types/caper-app.d.ts'), '// types', 'utf-8');
+    setMtime(path.join(cwd, 'caper.config.ts'), 100);
+    setMtime(path.join(cwd, 'src/types/caper-app.d.ts'), 50);
+
+    const first = await runChecks(cwd, { online: false });
+    expect(find(first, 'app-types').status).toBe('ok');
+
+    fs.mkdirSync(path.join(cwd, 'src/scenes'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, 'src/scenes/Example.ts'), '// scene', 'utf-8');
+    setMtime(path.join(cwd, 'src/scenes/Example.ts'), 10);
+
+    const second = await runChecks(cwd, { online: false });
+    expect(find(second, 'app-types').status).toBe('warn');
+  });
+
+  it('warns when the agent pointer version does not match the installed version', async () => {
+    const cwd = makeTempDir();
+
+    const block = `${START_MARKER}
+## Caper agent pointers
+
+This app runs on \`@caperjs/core@0.0.1\`.
+
+- Before engine-facing work, load the \`caper\` skill at \`.claude/skills/caper/SKILL.md\`.
+${END_MARKER}`;
+    fs.writeFileSync(path.join(cwd, 'AGENTS.md'), block, 'utf-8');
+    fs.mkdirSync(path.join(cwd, '.claude/skills/caper'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.claude/skills/caper/SKILL.md'), '# skill', 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+    const agent = find(checks, 'agent');
+
+    expect(agent.status).toBe('warn');
+    expect(agent.hint).toContain('@caperjs/core@0.0.1');
+  });
+
+  it('reports agent pointers ok when the block and skill are current', async () => {
+    const cwd = makeTempDir();
+
+    await agentInit(cwd);
+
+    const checks = await runChecks(cwd, { online: false });
+    expect(find(checks, 'agent').status).toBe('ok');
+  });
+
+  it('reports a linked package missing its build', async () => {
+    const cwd = makeTempDir();
+    const checkout = path.join(cwd, 'checkout');
+    fs.mkdirSync(path.join(checkout, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'src/a.ts'), '// a', 'utf-8');
+
+    const linkPath = path.join(cwd, 'node_modules/@caperjs/core');
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(checkout, linkPath, 'dir');
+
+    const checks = await runChecks(cwd, { online: false });
+    const link = find(checks, 'link');
+
+    expect(link.status).toBe('fail');
+    expect(link.label).toContain('linked from');
+    expect(link.hint).toContain('pnpm build');
+  });
+
+  it('reports a linked package ok when the build is newer than source', async () => {
+    const cwd = makeTempDir();
+    const checkout = path.join(cwd, 'checkout');
+
+    fs.mkdirSync(path.join(checkout, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'src/a.ts'), '// a', 'utf-8');
+    setMtime(path.join(checkout, 'src/a.ts'), 50);
+
+    fs.mkdirSync(path.join(checkout, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'lib/caper.mjs'), '// build', 'utf-8');
+    setMtime(path.join(checkout, 'lib/caper.mjs'), 10);
+
+    const linkPath = path.join(cwd, 'node_modules/@caperjs/core');
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(checkout, linkPath, 'dir');
+
+    const checks = await runChecks(cwd, { online: false });
+    const link = find(checks, 'link');
+
+    expect(link.status).toBe('ok');
+    expect(link.label).toContain('linked from');
+  });
+});