caracms 0.8.2 → 0.9.0

package/README.md

@@ -48,7 +48,7 @@ npm install
 
 `init` adds the plumbing (the Node adapter, the integration, a minimal `caracms.config.ts`
 and page component, the one catch-all route that serves every document with an address,
-the schemas) and links caracms's
+the schemas) and copies caracms's
 skills into `.claude/skills/`. It doesn't touch the site's pages. Bringing them in is the
 job of the `caracms-adopt` skill, one page at a time.
 
@@ -74,7 +74,8 @@ Run from the site's root:
 - `caracms start`: serve the built site (Hosting, below).
 
 The skills (`caracms-content`, `caracms-blocks`, `caracms-adopt`, `caracms-tina` and
-`caracms-hosting`, in `skills/`) say how the rest works, matching the installed version.
+`caracms-hosting`, in `site-skills/`) say how the rest works. `init` copies them into the site, and brings
+them up to date after an upgrade; `astro dev` and `caracms validate` say when they're behind.
 
 ## Collections and addresses
 
@@ -369,7 +370,7 @@ export default defineSite({
   (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set. Make a key for it in
   app.caracms.com." (the build fails; a running server's `/admin` answers 503 with it, and
   the public site keeps serving). It never falls back to the self-hosted variables.
-  `astro dev` without a key is local mode, as always.
+  `astro dev` is local mode, with or without the key (see [working locally](#working-locally)).
 - **`'self-hosted'`**: the site's own variables, as [the variables](#the-variables) list
   them. A `CARACMS_CLOUD_KEY` beside them is ignored the same way.
 - **Not set** (a site from before caracms 0.8.0): the key decides, and setting it beside
@@ -538,11 +539,13 @@ has been replaced.
 laptop, a colleague's, a client's developer, a staging deploy. Each gets **its own key**
 for the site, labelled ("Rich's laptop", "staging") in app.caracms.com, so revoking one
 never touches the live site. Leave `CARACMS_CLOUD_URL` unset: images render from
-`img.caracms.cloud` and the library lists the site's real folder. A cloud key turns
-`astro dev` into live mode on the site's real repo, as the App's variables do. Uploads
+`img.caracms.cloud` and the library lists the site's real folder. `astro dev` stays in
+local mode, editing the files on disk: live mode on a laptop never points at the site's
+real repo, so the key alone never turns it on (the App's variables still do). Uploads
 from a laptop land in the real folder and count towards its storage, which is harmless:
 nothing is overwritten or deleted, and nothing is live until it's published.
-`CARACMS_CLOUD_URL` is only for working on CaraCMS Cloud itself, against its dev deployment.
+`CARACMS_CLOUD_URL` is only for working on CaraCMS Cloud itself, against its dev deployment;
+with it, `astro dev` is live on that deployment's throwaway repos.
 
 ### Behind Cloudflare
 

package/bin/init.mjs

@@ -19,20 +19,23 @@
 //   left as they are on a site that already has the file (runs-anywhere Decision 12).
 //   Otherwise init writes no host file and prints the variables any host needs
 //   (HOST_VARIABLES), on the dry run and on `--write`.
-// - Run again, it re-links the skills, refreshes the CLAUDE.md block and the schemas, and
+// - Run again, it refreshes the skills (copies, skills.mjs), the CLAUDE.md block and the schemas, and
 //   reports the rest as already done.
 //
-// Plain JavaScript importing only Node built-ins and media.mjs (and, for the schemas and the
+// Plain JavaScript importing only Node built-ins, media.mjs and skills.mjs (and, for the schemas and the
 // config's `services`, the site's own Vite through site-runner.mjs), so it runs on Node
 // 22.12 with no flags.
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_CLOUD_URL, OWN_MEDIA_NAMES, parseDotenv, REPLACED_NAMES } from './media.mjs';
+import { skillNames, skillsPlan } from './skills.mjs';
+
+export { skillNames };
 
 const packageRoot = fileURLToPath(new URL('..', import.meta.url));
 const templates = fileURLToPath(new URL('./templates/', import.meta.url));
@@ -86,8 +89,6 @@ export const VERSIONS = { node: '^11.1.7', railway: '^3.16.0' };
 
 export const MARK_START = '<!-- caracms:start -->';
 export const MARK_END = '<!-- caracms:end -->';
-/** Where a site's skills link to: the installed package (Decision 12). */
-const SKILLS_LINK_BASE = '../../node_modules/caracms/skills/';
 /** The URLs the package reserves (src/slug.ts → addressProblem). */
 const RESERVED = ['/admin', '/_caracms', '/files'];
 const ROUTE_EXTENSIONS = ['.astro', '.md', '.mdx', '.markdown', '.html', '.ts', '.js', '.mjs', '.mts'];
@@ -562,8 +563,8 @@ export async function askMode({ input = process.stdin, output = process.stdout }
 // ── The changes ─────────────────────────────────────────────────────────────────
 
 /**
- * Everything init would do, as a list of changes ({ kind: 'add' | 'edit' | 'link' |
- * 'unlink' | 'schemas', file, before?, after?, target? }), notes (printed, nothing written),
+ * Everything init would do, as a list of changes ({ kind: 'add' | 'edit' |
+ * 'remove' | 'unlink' | 'schemas', file, before?, after?, why?, skill? }), notes (printed, nothing written),
  * and what's already done.
  */
 function changesOf(site, { railway = false, mode = null, field = null } = {}) {
@@ -662,24 +663,13 @@ function changesOf(site, { railway = false, mode = null, field = null } = {}) {
 		notes.push(railwayNeeds(railwayFile, mode));
 	} else done.push(railwayFile);
 
-	// Skills (Decision 12), linked from the installed package.
+	// Skills (Decision 12; copies since 0.9.0, skills.mjs).
 	const skills = skillNames();
-	const skillsDir = join(root, '.claude/skills');
-	for (const name of skills) {
-		const file = `.claude/skills/${name}`;
-		const target = `${SKILLS_LINK_BASE}${name}`;
-		const st = lstat(join(root, file));
-		if (!st) changes.push({ kind: 'link', file, target });
-		else if (st.isSymbolicLink() && readlinkSync(join(root, file)) === target) done.push(file);
-		else if (st.isSymbolicLink() && readlinkSync(join(root, file)).startsWith(SKILLS_LINK_BASE)) changes.push({ kind: 'link', file, target, replace: true });
-		else notes.push(`${file} is the site's own, so init doesn't link caracms's ${name} skill over it.`);
-	}
-	if (isDir(skillsDir)) {
-		for (const name of readdirSync(skillsDir).sort()) {
-			const path = join(skillsDir, name);
-			if (skills.includes(name) || !lstat(path)?.isSymbolicLink()) continue;
-			if (readlinkSync(path).startsWith(SKILLS_LINK_BASE)) changes.push({ kind: 'unlink', file: `.claude/skills/${name}` });
-		}
+	{
+		const s = skillsPlan(root);
+		changes.push(...s.changes);
+		notes.push(...s.notes);
+		done.push(...s.done);
 	}
 
 	// The CLAUDE.md block (Decision 12): into the link's target when CLAUDE.md is a link.
@@ -692,12 +682,59 @@ function changesOf(site, { railway = false, mode = null, field = null } = {}) {
 		if (after === null) notes.push(`${file} has a ${MARK_START} line with no ${MARK_END} after it, so init can't tell where its block ends and leaves the file alone. Replace the old block with this one by hand, then run init again:\n${block.split('\n').map((l) => `    ${l}`).join('\n')}`);
 		else edit(file, before, after, `${file} (the caracms block)`);
 	}
+	// pnpm 12.11+ asked to approve the skills caracms shipped before 0.9.0; approving wrote `permissions:
+	// caracms: skills: true`, which fails an install that runs before the repo is copied in (Railway's,
+	// Urban Return 2026-10-28). The package no longer ships skills pnpm links, so it's taken back out.
+	{
+		const before = read(join(root, 'pnpm-workspace.yaml'));
+		const after = before === null ? null : withoutSkillsApproval(before);
+		if (after === undefined) notes.push(`pnpm-workspace.yaml approves caracms's agent skills in a shape init can't edit. Take the approval out by hand (the \`skills: true\` under \`permissions:\` → \`caracms:\`): it fails an install that runs before the repo is copied in, Railway's for one, and init copies the skills in itself.`);
+		else if (after !== null && after !== before) {
+			changes.push({ kind: 'edit', file: 'pnpm-workspace.yaml', before, after });
+			notes.push(`pnpm-workspace.yaml approved caracms's agent skills (\`pnpm approve\`), so init takes that out: the approval fails an install that runs before the repo is copied in, Railway's for one, and init copies the skills in itself. pnpm won't ask about caracms again.`);
+		}
+	}
 	// MEC trial item 1: what Tina left behind, untracked (tinaOf).
 	const { leftover } = tinaOf(site);
 	if (leftover) notes.push(`${leftover.length ? leftover.join(', ') : 'tina/'} ${leftover.length > 1 ? 'are' : 'is'} left over from Tina (nothing under tina/ is tracked): delete ${leftover.length > 1 ? 'them' : 'it'}.`);
 	return { changes, notes, done, hostVariables: !railway && !hasRailway };
 }
 
+/**
+ * pnpm-workspace.yaml's text without the approval of caracms's agent skills (`permissions:` →
+ * `caracms:` → `skills: true`), emptied parents and all; the same text when there's none.
+ * Undefined when there is one in a shape these lines can't follow (a flow mapping, say).
+ */
+export function withoutSkillsApproval(text) {
+	const lines = text.split('\n');
+	const indent = (l) => /^ */.exec(l)[0].length;
+	const blank = (l) => /^\s*(#.*)?$/.test(l);
+	// The lines under `lines[at]`: everything indented deeper, up to the next line that isn't.
+	const childrenOf = (at) => {
+		const out = [];
+		for (let i = at + 1; i < lines.length; i++) {
+			if (blank(lines[i])) continue;
+			if (indent(lines[i]) <= indent(lines[at])) break;
+			out.push(i);
+		}
+		return out;
+	};
+	const top = lines.findIndex((l) => /^permissions:\s*(#.*)?$/.test(l));
+	if (top === -1) return /^permissions:/m.test(text) && /caracms/.test(text) ? undefined : text;
+	const under = childrenOf(top);
+	const pkg = under.find((i) => /^\s+(['"]?)caracms\1:/.test(lines[i]));
+	if (pkg === undefined) return text;
+	const rest = lines[pkg].replace(/^\s+(['"]?)caracms\1:/, '').replace(/#.*$/, '').trim();
+	if (rest) return /skills\s*:\s*true/.test(rest) ? undefined : text;
+	const own = childrenOf(pkg);
+	const skills = own.find((i) => /^\s+skills:\s*true\s*(#.*)?$/.test(lines[i]));
+	if (skills === undefined) return /skills\s*:\s*true/.test(own.map((i) => lines[i]).join('\n')) ? undefined : text;
+	const drop = new Set([skills]);
+	if (own.length === 1) drop.add(pkg);
+	if (own.length === 1 && under.every((i) => i === pkg || own.includes(i))) drop.add(top);
+	return lines.filter((_, i) => !drop.has(i)).join('\n');
+}
+
 /** `object` with `key` added, in alphabetical order when the object already is. */
 function withKey(object, key, value) {
 	if (Object.hasOwn(object, key)) return object;
@@ -810,13 +847,6 @@ function railwayNeeds(file, mode = null) {
 	].join('\n');
 }
 
-/** The package's skills: its `skills/<name>/` folders. */
-export function skillNames() {
-	const dir = join(packageRoot, 'skills');
-	if (!isDir(dir)) return [];
-	return readdirSync(dir).filter((n) => !n.startsWith('.') && isDir(join(dir, n))).sort();
-}
-
 /**
  * @param {string[]} skills
  * @param {string | null} [mode] the config's `services`; null: not set
@@ -828,7 +858,7 @@ export function claudeBlock(skills, mode = null) {
 		'',
 		MODE_LINES[mode ?? 'none'],
 		'',
-		"This site's content is edited with caracms (the `caracms` package). Its skills are linked from the installed package into `.claude/skills/`, so they always match the installed version:",
+		"This site's content is edited with caracms (the `caracms` package). Its skills are copied from the installed package into `.claude/skills/` by `caracms init`, which brings them up to date after an upgrade (`astro dev` and `caracms validate` say when they're behind):",
 		'',
 		...skills.map((name) => `- \`${name}\`${SKILL_BLURBS[name] ? `: ${SKILL_BLURBS[name]}.` : ''}`),
 		...(skills.length ? [''] : []),
@@ -893,10 +923,10 @@ function describe(change) {
 			return `  add     ${change.file}`;
 		case 'edit':
 			return `  edit    ${change.file}`;
-		case 'link':
-			return `  link    ${change.file} → ${change.target}`;
+		case 'remove':
+			return `  remove  ${change.file} (${change.why})`;
 		case 'unlink':
-			return `  unlink  ${change.file} (that skill is no longer in the package)`;
+			return `  unlink  ${change.file} (${change.why})`;
 		case 'schemas':
 			return `  ${change.before === null ? 'add   ' : change.after === null ? 'remove' : 'edit  '}  ${change.file}${change.generated ? ' (generated: caracms schemas)' : ''}`;
 	}
@@ -911,7 +941,7 @@ function report({ changes, notes, done, hostVariables, mode, where, site }, { wr
 		parts.push(write ? 'caracms init: done. It changed:' : 'caracms init: the change it would make. Nothing is written: `caracms init --write` applies exactly this.');
 		parts.push(changes.map(describe).join('\n'));
 		if (!write) {
-			const diffs = changes.filter((c) => (c.kind === 'add' || c.kind === 'edit' || (c.kind === 'schemas' && !c.generated && c.after !== null)));
+			const diffs = changes.filter((c) => (((c.kind === 'add' || c.kind === 'edit') && !c.skill) || (c.kind === 'schemas' && !c.generated && c.after !== null)));
 			if (diffs.length) parts.push(diffs.map((c) => diff(c.file, c.before ?? null, c.after)).join('\n\n'));
 		}
 	}
@@ -1008,13 +1038,11 @@ function apply(root, changes) {
 				mkdirSync(dirname(path), { recursive: true });
 				writeFileSync(path, c.after);
 				break;
-			case 'link':
-				mkdirSync(dirname(path), { recursive: true });
-				if (c.replace) rmSync(path, { force: true });
-				symlinkSync(c.target, path);
-				break;
+			case 'remove':
 			case 'unlink':
 				rmSync(path, { force: true });
+				// A skill folder left empty goes too (skills.mjs: a skill the package no longer has).
+				for (let dir = dirname(path); c.kind === 'remove' && dir.startsWith(join(root, '.claude/skills/')) && readdirSync(dir).length === 0; dir = dirname(dir)) rmSync(dir, { recursive: true });
 				break;
 			// 'schemas' is written by the schemas command, after everything else.
 		}

package/bin/skills.mjs

@@ -0,0 +1,196 @@
+// The skills caracms puts in a site: the package's `site-skills/<name>/` folders, copied into the
+// site's `.claude/skills/<name>/` by `caracms init`, with a stamp of what was copied
+// (`.claude/skills/.caracms.json`: each file's hash). Copies, not links (0.9.0): pnpm 12.11+ asks
+// to approve any package that ships `skills/<name>/SKILL.md`, and an approval fails an install
+// that runs before the repo is copied in (Railway's). So the package keeps them in `site-skills/`,
+// which pnpm doesn't look in, and a site's copies work on a fresh clone with nothing installed.
+//
+// The stamp is how init tells a copy it may refresh from one someone edited: a file whose hash
+// is still the stamp's is caracms's, and is brought up to date; one that isn't is left alone,
+// with a note. `astro dev` and `caracms validate` say when the copies are behind (skillsWarning).
+//
+// Plain JavaScript importing only Node built-ins: init.mjs, validate and the integration share it.
+
+import { createHash } from 'node:crypto';
+import { lstatSync, readdirSync, readFileSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+const source = join(packageRoot, 'site-skills');
+export const SKILLS_DIR = '.claude/skills';
+export const STAMP = `${SKILLS_DIR}/.caracms.json`;
+/** Where 0.8 and earlier linked a site's skills to. */
+export const OLD_LINK_BASE = '../../node_modules/caracms/skills/';
+
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const lstat = (path) => lstatSync(path, { throwIfNoEntry: false }) ?? null;
+const read = (path) => {
+	try {
+		return readFileSync(path, 'utf8');
+	} catch {
+		return null;
+	}
+};
+
+/** The package's skills: its `site-skills/<name>/` folders. */
+export function skillNames() {
+	if (!lstat(source)?.isDirectory()) return [];
+	return readdirSync(source, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+		.map((d) => d.name)
+		.sort();
+}
+
+/** The files under `dir`, as `/`-separated paths relative to it, sorted. */
+function filesUnder(dir, prefix = '') {
+	const out = [];
+	for (const d of readdirSync(dir, { withFileTypes: true })) {
+		if (d.name.startsWith('.')) continue;
+		const rel = `${prefix}${d.name}`;
+		if (d.isDirectory()) out.push(...filesUnder(join(dir, d.name), `${rel}/`));
+		else if (d.isFile()) out.push(rel);
+	}
+	return out.sort();
+}
+
+/** The package's skill files: `<name>/<file>` → text. */
+function packageFiles() {
+	const out = new Map();
+	for (const name of skillNames()) for (const file of filesUnder(join(source, name))) out.set(`${name}/${file}`, readFileSync(join(source, name, file), 'utf8'));
+	return out;
+}
+
+/** The stamp's hashes (`<name>/<file>` → hash), or null when there's no stamp or it doesn't parse. */
+function stampOf(root) {
+	try {
+		const files = JSON.parse(read(join(root, STAMP)) ?? '').files;
+		return files && typeof files === 'object' ? files : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * What init does to bring a site's `.claude/skills/` to the package's skills, as init's changes
+ * (`add`, `edit`, `remove` and `unlink`; a skill file's carry `skill: true`, so a dry run lists
+ * them without diffs), notes and what's already done.
+ * @param {string} root
+ */
+export function skillsPlan(root) {
+	const changes = [];
+	const notes = [];
+	const done = [];
+	const wanted = packageFiles();
+	const stamp = stampOf(root) ?? {};
+	const next = {};
+	const at = (rel) => `${SKILLS_DIR}/${rel}`;
+	const mine = (rel, text) => stamp[rel] !== undefined && hash(text) === stamp[rel];
+
+	for (const name of skillNames()) {
+		const dir = at(name);
+		const st = lstat(join(root, dir));
+		const files = [...wanted.keys()].filter((rel) => rel.startsWith(`${name}/`));
+		const fresh = () => {
+			for (const rel of files) {
+				changes.push({ kind: 'add', file: at(rel), after: wanted.get(rel), skill: true });
+				next[rel] = hash(wanted.get(rel));
+			}
+		};
+		if (st?.isSymbolicLink()) {
+			if (!readlinkSync(join(root, dir)).startsWith(OLD_LINK_BASE)) {
+				notes.push(`${dir} is the site's own (a link elsewhere), so init doesn't copy caracms's ${name} skill over it.`);
+				continue;
+			}
+			// 0.8 and earlier: a link into node_modules, now a copy.
+			changes.push({ kind: 'unlink', file: dir, why: 'a link into node_modules, now a copy' });
+			fresh();
+			continue;
+		}
+		if (!st) {
+			fresh();
+			continue;
+		}
+		// Caracms's when the stamp names it, or when every file is caracms's word for word (a lost stamp).
+		const ours = Object.keys(stamp).some((rel) => rel.startsWith(`${name}/`)) || (st.isDirectory() && files.every((rel) => read(join(root, at(rel))) === wanted.get(rel)));
+		if (!st.isDirectory() || !ours) {
+			notes.push(`${dir} is the site's own, so init doesn't copy caracms's ${name} skill over it.`);
+			continue;
+		}
+		let current = true;
+		for (const rel of files) {
+			const want = wanted.get(rel);
+			const have = read(join(root, at(rel)));
+			if (have === want) next[rel] = hash(want);
+			else if (have === null || mine(rel, have)) {
+				changes.push({ kind: have === null ? 'add' : 'edit', file: at(rel), before: have, after: want, skill: true });
+				next[rel] = hash(want);
+				current = false;
+			} else {
+				notes.push(`${at(rel)} has been edited here, so init leaves it as it is. caracms's own is node_modules/caracms/site-skills/${rel}: bring your changes across, or delete the file and run init again.`);
+				if (stamp[rel] !== undefined) next[rel] = stamp[rel];
+				current = false;
+			}
+		}
+		// Files caracms copied that the skill no longer has.
+		for (const rel of Object.keys(stamp).filter((r) => r.startsWith(`${name}/`) && !wanted.has(r))) {
+			const have = read(join(root, at(rel)));
+			if (have === null) continue;
+			if (mine(rel, have)) changes.push({ kind: 'remove', file: at(rel), why: 'no longer in the skill' });
+			else {
+				notes.push(`${at(rel)} is no longer in caracms's ${name} skill, but it has been edited here, so init leaves it.`);
+				next[rel] = stamp[rel];
+			}
+			current = false;
+		}
+		if (current) done.push(dir);
+	}
+
+	// Skills the package no longer has: their copies (when unedited) and their 0.8 links.
+	const names = new Set(skillNames());
+	for (const rel of Object.keys(stamp).filter((r) => !names.has(r.split('/')[0]))) {
+		const have = read(join(root, at(rel)));
+		if (have === null) continue;
+		if (mine(rel, have)) changes.push({ kind: 'remove', file: at(rel), why: 'that skill is no longer in the package' });
+		else {
+			notes.push(`${at(rel)} is from a skill caracms no longer has, but it has been edited here, so init leaves it.`);
+			next[rel] = stamp[rel];
+		}
+	}
+	const dirPath = join(root, SKILLS_DIR);
+	if (lstat(dirPath)?.isDirectory()) {
+		for (const name of readdirSync(dirPath).sort()) {
+			if (names.has(name) || !lstat(join(dirPath, name))?.isSymbolicLink()) continue;
+			if (readlinkSync(join(dirPath, name)).startsWith(OLD_LINK_BASE)) changes.push({ kind: 'unlink', file: at(name), why: 'that skill is no longer in the package' });
+			// pnpm's own links, from an approval of 0.8's skills (gitignored, so only on that machine): each skill twice.
+			else if (name.startsWith('pnpm-caracms-')) changes.push({ kind: 'unlink', file: at(name), why: "pnpm's link from an approval, a second copy of a skill" });
+		}
+	}
+
+	const before = read(join(root, STAMP));
+	const after = `${JSON.stringify({ about: "caracms's skills as `caracms init` copied them: it refreshes a file whose hash is still this one, and leaves an edited one alone.", files: next }, null, 2)}\n`;
+	if (before !== after && (changes.length || Object.keys(next).length)) changes.push({ kind: before === null ? 'add' : 'edit', file: STAMP, before, after, skill: true });
+	return { changes, notes, done };
+}
+
+/**
+ * One sentence when the site's copies are behind the installed package (what `astro dev` and
+ * `caracms validate` warn), else null. Only for a site that has caracms's skills already (a
+ * stamp, or 0.8's links): one that never ran init, or took them out, gets nothing.
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function skillsWarning(root) {
+	const linked = (() => {
+		const dirPath = join(root, SKILLS_DIR);
+		if (!lstat(dirPath)?.isDirectory()) return false;
+		return readdirSync(dirPath).some((n) => lstat(join(dirPath, n))?.isSymbolicLink() && readlinkSync(join(dirPath, n)).startsWith(OLD_LINK_BASE));
+	})();
+	if (!linked && stampOf(root) === null) return null;
+	const behind = skillsPlan(root).changes.some((c) => c.file !== STAMP);
+	if (!behind) return null;
+	const version = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+	return linked
+		? `${SKILLS_DIR} links caracms's skills from node_modules, and caracms ${version} copies them in instead: run \`npx caracms init --write\` and commit the result.`
+		: `${SKILLS_DIR} is behind the skills of the installed caracms (${version}): run \`npx caracms init --write\` and commit the result.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
   "files": [
     "src",
     "bin",
-    "skills",
+    "site-skills",
     "README.md",
     "LICENSE"
   ],

package/{skills → site-skills}/caracms-adopt/SKILL.md

@@ -33,8 +33,8 @@ Start from a clean git checkout (untracked files are fine). The order is:
 **`npx caracms init --cloud`** (or `--self-hosted`) without `--write` is a dry run: it
 writes nothing and prints
 
-- one line per file: `add` (a new file), `edit` (an existing one), `link` / `unlink` (a
-  skill link in `.claude/skills/`);
+- one line per file: `add` (a new file), `edit` (an existing one), `remove` / `unlink` (a
+  skill file or link in `.claude/skills/` that goes);
 - a diff of each;
 - `Already done: …` on a site partly set up;
 - `Notes:`, things it can't do itself, with the lines to add by hand (an `astro.config` it
@@ -56,11 +56,12 @@ to tracked files: usually the install of step 1, not yet committed.
 Read the diff. Then **`npx caracms init --cloud --write`** (or `--self-hosted --write`),
 install again (`npm install` / `pnpm install`), and commit that as one change.
 
-pnpm 12.11 and later may print `Agent skills awaiting approval: caracms` after the install.
-That's pnpm's own gate: it links the skills a dependency ships into `.claude/skills/` only
-once you approve them with `pnpm approve` (`pnpm permissions` lists what's waiting).
-`init` has already linked caracms's skills itself, so there's nothing to do; leave it
-unapproved, and don't approve it in passing (`pnpm approve` also reviews build scripts).
+caracms's skills are copied into `.claude/skills/` by `init`, as real files committed with
+the site, so they work on a fresh clone with nothing installed. pnpm doesn't ask to approve
+them (since 0.9.0 the package keeps them where pnpm doesn't look). A site that approved
+0.8's has `permissions: caracms: skills: true` in `pnpm-workspace.yaml`, which fails an
+install that runs before the repo is copied in (Railway's, `ERR_PNPM_NO_AGENT_SKILLS_DIR`):
+`init --write` takes it out.
 
 `init` added:
 
@@ -76,7 +77,7 @@ unapproved, and don't approve it in passing (`pnpm approve` also reviews build s
   `devToolbar: { enabled: false }`;
 - `package.json`: `@astrojs/node`, `"start": "caracms start"`;
   `.gitignore`: `.caracms/`; the tsconfig's `allowImportingTsExtensions`;
-- the skill links and a block in `CLAUDE.md`;
+- the skills, copied into `.claude/skills/` with a stamp (`.caracms.json`) of what it copied, and a block in `CLAUDE.md`;
 - with `--railway` only, `.railway/railway.ts` (when the site had none) and `railway`
   (dev). Without it, `init` prints the variables any host needs instead. Where and how
   the site runs (Railway, Render, Fly, a VPS) is `caracms-hosting` → section 2.
@@ -87,8 +88,8 @@ the output moves to `dist/client/` and `dist/server/`, and `npm start` is now
 (its own built-site checks, a script) needs the new paths: the pages are in
 `dist/client/`.
 
-Re-run `init` after updating caracms: it reads the mode from the config, re-links the
-skills and refreshes the CLAUDE.md block and the schemas. On a set-up site with nothing
+Re-run `init` after updating caracms: it reads the mode from the config, refreshes the
+skills (leaving any file edited here alone, with a note), the CLAUDE.md block and the schemas. On a set-up site with nothing
 to do it says
 `caracms init: nothing to do. caracms is set up here.`
 
@@ -115,7 +116,7 @@ is the exception (section 4).
 **Images need credentials** in the site's `.env` (never committed). On CaraCMS Cloud
 that's `CARACMS_CLOUD_KEY` alone: a key labelled for this laptop, made in
 app.caracms.com (`caracms-hosting` → section 1); it shows, imports and uploads images,
-and makes `astro dev` live on the site's real repo. Self-hosted, it's the media
+and `astro dev` still edits the files on disk. Self-hosted, it's the media
 variables: `CARACMS_MEDIA_URL` (imgproxy's origin), `IMGPROXY_KEY`, `IMGPROXY_SALT` and
 `S3_BUCKET` to show images, plus `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID` and
 `S3_SECRET_ACCESS_KEY` to import and upload them. Without them `astro dev` draws a

package/{skills → site-skills}/caracms-hosting/SKILL.md

@@ -81,8 +81,9 @@ npx caracms init --cloud --write    # writes services: 'cloud' and the rest
 **One key per place the site runs**, each labelled in app.caracms.com: "Railway" for
 the host, "Rich's laptop" for a laptop's `.env`, "staging" for a staging deploy.
 Revoking one never touches the others. Leave `CARACMS_CLOUD_URL` unset (it's only for
-working on CaraCMS Cloud itself). On a laptop a cloud key makes `astro dev` live on the
-site's real repo and folder; without one, `astro dev` edits content on disk as always.
+working on CaraCMS Cloud itself). On a laptop `astro dev` edits content on disk, with or
+without a key; the key shows, imports and uploads images in the site's real folder. Only
+the key with `CARACMS_CLOUD_URL` (the cloud's dev deployment) makes `astro dev` live.
 
 **A production build needs the key.** With `services: 'cloud'` and no
 `CARACMS_CLOUD_KEY`, `astro build` (and `pnpm build` on a laptop, which is a production

package/{skills → site-skills}/caracms-tina/SKILL.md

@@ -91,7 +91,7 @@ Work on a branch (`caracms-port`, say) in a worktree of the site. Commit after e
 
 ## 2. The conversion script
 
-Copy `node_modules/caracms/skills/caracms-tina/tina-to-caracms.mjs` into the site's own
+Copy `.claude/skills/caracms-tina/tina-to-caracms.mjs` into the site's own
 `scripts/`. The site's copy is the one that runs; it's committed with the site.
 
 **Adapt only the table under `ADAPT HERE`** (the script's header says what each entry is):

package/src/cli/validate.ts

@@ -41,6 +41,7 @@ import { sameAddress } from '../slug.ts';
 import { hiddenDocuments, hiddenPages } from '../links.ts';
 import { runSchemas, schemaFileChanges, schemasReport } from './schemas.ts';
 import { jsonFilesUnder, loadSite } from './site.ts';
+import { skillsWarning } from '../../bin/skills.mjs';
 
 export interface Finding {
 	/** Relative to the site's root. */
@@ -475,6 +476,9 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 			message: change.text === null ? 'The config no longer makes this schema. `caracms schemas` removes it.' : change.before === null ? 'This schema file is missing. `caracms schemas` writes it.' : "This schema file is out of date with caracms.config.ts. `caracms schemas` rewrites it.",
 		});
 	}
+	// The skills init copied in (bin/skills.mjs), when the installed caracms has newer ones. A warning: old docs never fail a pull request.
+	const skills = skillsWarning(site.root);
+	if (skills) report.warnings.push({ file: '.claude/skills', path: '', message: skills });
 	return report;
 }
 

package/src/index.ts

@@ -58,6 +58,7 @@ import { resolveSite, SITE_SETTINGS_FILE, type ResolvedSite, type SiteConfig } f
 import { lockupCss } from './lockup-css.ts';
 import { shareBuildReads } from './read.ts';
 import { writeSchemaFiles } from './cli/schemas.ts';
+import { skillsWarning } from '../bin/skills.mjs';
 import { configFile } from './cli/site.ts';
 import { pagesRoutes } from './code-routes-disk.ts';
 import { codeRoutesFrom } from './code-routes.ts';
@@ -523,6 +524,13 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				} catch (error) {
 					logger.warn(`couldn't write schemas/: ${(error as Error).message}`);
 				}
+				// The skills init copied in (bin/skills.mjs): one line when the installed caracms has newer ones.
+				try {
+					const skills = skillsWarning(site.root);
+					if (skills) logger.warn(skills);
+				} catch {
+					// A warning about docs never stops the dev server.
+				}
 				// A content change re-runs every route's getStaticPaths, as Astro does for its own content
 				// collections (the same event, to the same server environments). Never a browser reload:
 				// the editor writes these files.

package/src/live/mode.ts

@@ -1,8 +1,11 @@
 /**
  * Which mode the editor runs in, read from the environment (M4 Decision 1).
  *
- * - **Local mode**: `astro dev` with no GitHub credentials (`CARACMS_CLOUD_KEY`,
- *   `GITHUB_APP_ID` or `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
+ * - **Local mode**: `astro dev` with no GitHub credentials (`GITHUB_APP_ID` or
+ *   `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk. `CARACMS_CLOUD_KEY` alone stays
+ *   local (caracms-cloud: live mode on a laptop never points at a client's repo); the key
+ *   is still the images', clips' and forms' credential there. Only the key with
+ *   `CARACMS_CLOUD_URL` (the cloud's dev deployment, throwaway repos only) is live in dev.
  * - **Live mode**: whenever a credential is configured, and **always on a production
  *   server**. It needs one GitHub credential (a fine-grained token, or the App's
  *   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`; runs-anywhere Decisions 3–4), the repo
@@ -208,7 +211,9 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 	// Never GITHUB_TOKEN (Decision 4): the gh CLI and GitHub Actions export it.
 	const ghToken = get('CARACMS_GITHUB_TOKEN');
 	const cloudKey = get('CARACMS_CLOUD_KEY');
-	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken && !cloudKey) return { kind: 'local' };
+	// A laptop's key is the production cloud's, so the site's real repo: dev stays local unless CARACMS_CLOUD_URL names another cloud.
+	const devCloud = cloudKey && get('CARACMS_CLOUD_URL');
+	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken && !devCloud) return { kind: 'local' };
 
 	const missing: string[] = [];
 	const problems: string[] = [];