@avocadostudio-ai/skills 0.14.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Avocado Studio Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,54 @@
+# @avocadostudio-ai/skills
+
+Avocado Studio's setup instructions, as agent skills that ship with a version.
+
+```bash
+npx @avocadostudio-ai/skills
+```
+
+Run it in your project. It writes the skills an AI coding agent needs to work on
+an Avocado site — and nothing else. No routes, no config, no dependencies, no
+prompts.
+
+```
+.claude/skills/    for Claude Code
+.agents/skills/    for the cross-agent `skills` CLI (Cursor, Codex, Gemini)
+AGENTS.md          only if absent — yours is never overwritten
+CLAUDE.md          only if absent
+```
+
+Then ask your agent to add Avocado to the site. It will load `avocado`, which
+routes to one of `avocado-integrate`, `avocado-demo` or `avocado-blocks`.
+
+## Why a package and not a docs page
+
+A web page cannot be versioned against what npm serves. Ours drifted: the
+quickstart said `0.11.9` while the registry served `0.13.1`, and the two guides
+written for *existing* sites taught a `registerBlock` call that does not
+compile — in the one path where a reader had no working example to copy from
+instead. Nothing in the repo could have caught it, because none of it was in the
+repo.
+
+These move in lockstep with the code they describe. An 0.13.1 install carries
+0.13.1's instructions, and re-running after an upgrade replaces them.
+
+## Options
+
+| | |
+|---|---|
+| `[directory]` | Where to write. Defaults to the current directory. |
+| `--dry-run` | Print what would be written, write nothing. |
+
+Skill files are replaced on re-run — that is how an upgrade delivers new
+instructions, and every file's outcome is reported so a skill you had forked
+shows up as `updated` rather than changing silently. `AGENTS.md` and `CLAUDE.md`
+are yours and are only ever created.
+
+Scaffolding a new project instead? `npm create avocado-site` writes the same
+skills, from this package.
+
+Documentation: <https://docs.avocadostudio.dev>
+
+## License
+
+Apache-2.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { installSkills, skillNames } from "./index.js";
+/*
+ * `npx @avocadostudio-ai/skills` — the whole command.
+ *
+ * No prompts and no dependencies, because the thing it competes with is pasting
+ * a 460-line prompt into an agent, and anything that takes longer than that to
+ * run will lose to it. It writes instructions and nothing else: no routes, no
+ * manifest, no config. Wiring is a decision; reading is not, which is why this
+ * is a separate command from the scaffolder rather than a flag on it.
+ */
+const HELP = `avocado-skills — install Avocado Studio's agent skills into a project
+
+  npx @avocadostudio-ai/skills [directory] [options]
+
+Writes the skills an AI coding agent needs to work on an Avocado site, matched
+to the version of this package. Nothing else is touched: no routes, no config,
+no dependencies.
+
+Arguments
+  directory        Where to write. Defaults to the current directory.
+
+Options
+  --dry-run        Print what would be written, write nothing.
+  -h, --help       This.
+
+Written
+  .claude/skills/  for Claude Code
+  .agents/skills/  for the cross-agent "skills" CLI (Cursor, Codex, Gemini)
+  AGENTS.md        only if absent — yours is never overwritten
+  CLAUDE.md        only if absent
+
+Skill files are replaced on re-run, which is how an upgrade delivers new
+instructions. Docs: https://docs.avocadostudio.dev
+`;
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const dryRun = argv.includes("--dry-run");
+    const unknown = argv.filter((a) => a.startsWith("-") && a !== "--dry-run");
+    if (unknown.length > 0) {
+        process.stderr.write(`Unknown option: ${unknown.join(", ")}\n\n${HELP}`);
+        process.exitCode = 1;
+        return;
+    }
+    const target = resolve(argv.find((a) => !a.startsWith("-")) ?? process.cwd());
+    const version = await ownVersion();
+    const result = await installSkills(target, { siteName: await siteName(target), dryRun });
+    const verb = dryRun ? "Would install" : "Installed";
+    process.stdout.write(`${verb} ${skillNames().length} Avocado skills (${version}) into ${target}\n\n`);
+    for (const file of result.files) {
+        process.stdout.write(`  ${label(file.outcome)}  ${file.path}\n`);
+    }
+    if (result.pointerMissing) {
+        process.stdout.write(`\nYour AGENTS.md does not mention Avocado. Add a line pointing at the \`avocado\`\n` +
+            `skill so your agent loads it without being asked.\n`);
+    }
+    if (!dryRun) {
+        process.stdout.write(`\nNext: ask your coding agent to add Avocado to this site.\n`);
+    }
+}
+function label(outcome) {
+    return { created: "new    ", updated: "updated", unchanged: "same   ", kept: "kept   " }[outcome] ?? outcome;
+}
+/** The target's own name, for the `AGENTS.md` heading. */
+async function siteName(dir) {
+    try {
+        const pkg = JSON.parse(await readFile(resolve(dir, "package.json"), "utf-8"));
+        if (typeof pkg.name === "string" && pkg.name.length > 0)
+            return pkg.name;
+    }
+    catch {
+        // No package.json, or an unreadable one. The directory name is a fine title.
+    }
+    return basename(dir);
+}
+async function ownVersion() {
+    try {
+        const pkg = JSON.parse(await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where the skills land, relative to the project root. Both roots get the same
+ * bytes: `.claude/skills` is Claude Code's, and `.agents/skills` is what the
+ * cross-agent `skills` CLI reads, so Cursor, Codex, Copilot and Gemini find
+ * them too.
+ */
+export declare const SKILL_ROOTS: readonly [".claude/skills", ".agents/skills"];
+/** One file to write: where it goes, and the absolute path to copy it from. */
+export interface SkillFile {
+    /** Project-relative, POSIX-separated — it is written into a repo. */
+    path: string;
+    /** Absolute path in this package. */
+    source: string;
+}
+/** The directory this package's SKILL.md files are read from. */
+export declare function skillsDir(): string;
+/** The skill names shipped here, e.g. `avocado`, `avocado-integrate`. */
+export declare function skillNames(): string[];
+/** Every skill file, for each root. Deterministic order. */
+export declare function skillFiles(): SkillFile[];
+/**
+ * The router file every agent reads without being told to.
+ *
+ * Deliberately a pointer and not a copy: a second description of the same
+ * wiring is a second thing to keep true, and the skills are the ones that ship
+ * with the version. `CLAUDE.md` is one line pointing here for the same reason.
+ */
+export declare function agentsMd(siteName: string): string;
+export declare function claudeMd(): string;
+export { installSkills } from "./install.ts";
+export type { InstallOptions, InstallResult, FileOutcome } from "./install.ts";

package/dist/index.js

@@ -0,0 +1,102 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, posix, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/*
+ * Avocado's setup instructions, as files that ship with a version.
+ *
+ * The setup people actually run is "point a coding agent at my repo", and a web
+ * page is the worst possible carrier for that: nothing versions it against the
+ * packages. `docs-site/quickstart.mdx` sat pinned at `0.11.9` while npm served
+ * `0.13.1`, and the two guides written for *existing* sites taught
+ * `registerBlock({ type, schema, fields })` against a function whose signature
+ * is `(type, { schema, meta })` — three defects in four lines, in the one place
+ * a reader had no working example to copy from instead. Neither could have been
+ * caught by anything in the repo, because neither was in it.
+ *
+ * So they live here, in a package, and move in lockstep with the code they
+ * describe: an 0.13.1 install carries 0.13.1's instructions.
+ *
+ * This package is the single source of those bytes. `create-avocado-site`
+ * depends on it and writes the same files into a scaffold, so there is one copy
+ * and two delivery channels — `npx @avocadostudio-ai/skills` for a repo that
+ * already exists, and the scaffolder for one that does not.
+ */
+/**
+ * Where the skills land, relative to the project root. Both roots get the same
+ * bytes: `.claude/skills` is Claude Code's, and `.agents/skills` is what the
+ * cross-agent `skills` CLI reads, so Cursor, Codex, Copilot and Gemini find
+ * them too.
+ */
+export const SKILL_ROOTS = [".claude/skills", ".agents/skills"];
+/*
+ * Resolved relative to the package root, one level up from both `src/` and
+ * `dist/` — the same answer from source under tsx and from the published build.
+ */
+const SKILLS_DIR = fileURLToPath(new URL("../skills", import.meta.url));
+/** The directory this package's SKILL.md files are read from. */
+export function skillsDir() {
+    return SKILLS_DIR;
+}
+/** The skill names shipped here, e.g. `avocado`, `avocado-integrate`. */
+export function skillNames() {
+    return readdirSync(SKILLS_DIR)
+        .filter((entry) => statSync(join(SKILLS_DIR, entry)).isDirectory())
+        .sort();
+}
+/** Every skill file, for each root. Deterministic order. */
+export function skillFiles() {
+    const files = walk(SKILLS_DIR);
+    return SKILL_ROOTS.flatMap((root) => files.map((absolute) => ({
+        path: posix.join(root, absolute.slice(SKILLS_DIR.length + 1).split(sep).join("/")),
+        source: absolute,
+    })));
+}
+/**
+ * The router file every agent reads without being told to.
+ *
+ * Deliberately a pointer and not a copy: a second description of the same
+ * wiring is a second thing to keep true, and the skills are the ones that ship
+ * with the version. `CLAUDE.md` is one line pointing here for the same reason.
+ */
+export function agentsMd(siteName) {
+    return `# ${siteName}
+
+## Avocado Studio
+
+This project uses [Avocado Studio](https://docs.avocadostudio.dev) for
+chat-driven content editing.
+
+**Load the \`avocado\` skill before changing anything it touches** — blocks,
+the editor API routes, the orchestrator mount, the live preview, or the page
+factory. It is in \`.claude/skills/avocado/\` and routes to the task skill for
+the job:
+
+| Working on | Skill |
+|---|---|
+| Wiring Avocado into this site | \`avocado-integrate\` |
+| A demo, or a fresh project | \`avocado-demo\` |
+| Declaring components as editable blocks | \`avocado-blocks\` |
+
+The rule those skills exist to protect: **a component's props are not editable
+until a schema declares them.** An undeclared prop cannot be reached by any
+operation, prompt or model. Widening a schema to make an edit go through is a
+change to this site's safety boundary — raise it, do not do it quietly.
+
+Full documentation: https://docs.avocadostudio.dev/llms.txt
+`;
+}
+export function claudeMd() {
+    return `See [AGENTS.md](./AGENTS.md).\n`;
+}
+function walk(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...walk(full));
+        else
+            out.push(full);
+    }
+    return out.sort();
+}
+export { installSkills } from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,36 @@
+export type FileOutcome = {
+    path: string;
+    /**
+     * `created` — it was not there.
+     * `updated` — it was there with different bytes, and this is a skill file, so
+     *   it is ours to replace.
+     * `unchanged` — already byte-identical.
+     * `kept` — it was there and it is the project's own file, so it was left alone.
+     */
+    outcome: "created" | "updated" | "unchanged" | "kept";
+};
+export interface InstallOptions {
+    /** Heading for a generated `AGENTS.md`. Defaults to the directory name. */
+    siteName?: string;
+    /** Work out every outcome and write nothing. */
+    dryRun?: boolean;
+}
+export interface InstallResult {
+    files: FileOutcome[];
+    created: number;
+    updated: number;
+    unchanged: number;
+    kept: number;
+    /**
+     * Nothing in the project's `AGENTS.md` / `CLAUDE.md` names the skills, so an
+     * agent will not load them without being asked.
+     *
+     * This is the only thing a `kept` file can cost, and it is worth saying once.
+     * Saying it on *every* kept file would mean repeating the advice at somebody
+     * who already took it — the second run of this command writes nothing, keeps
+     * the `AGENTS.md` it wrote a minute ago, and has no business telling them to
+     * add a line that is already in it.
+     */
+    pointerMissing: boolean;
+}
+export declare function installSkills(dir: string, options?: InstallOptions): Promise<InstallResult>;

package/dist/install.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { agentsMd, claudeMd, skillFiles } from "./index.js";
+/*
+ * Two kinds of file, two different promises, and the difference is the whole
+ * design of this command.
+ *
+ * The SKILL.md files are *ours*. Overwriting them is not a hazard, it is the
+ * point: the reason these moved out of the docs site is that stale instructions
+ * are invisible until an agent follows them into a compile error, so re-running
+ * after an upgrade has to actually deliver the new bytes. A scaffolder that
+ * "never clobbers" would reintroduce exactly the drift this package exists to
+ * end — 0.14 installed, 0.13 instructions on disk, nothing saying so.
+ *
+ * `AGENTS.md` and `CLAUDE.md` are the *project's*. People write real content in
+ * those, about things that have nothing to do with us, and a tool that
+ * overwrites one has destroyed work it never wrote. Those are only ever
+ * created, never replaced, and the report says `kept` so the caller can see
+ * that the pointer to the skills may not be there.
+ *
+ * Every outcome is reported per file, so `updated` on a skill somebody had
+ * forked is visible rather than silent.
+ */
+export async function installSkills(dir, options = {}) {
+    const { dryRun = false } = options;
+    const siteName = options.siteName ?? "This project";
+    const ours = skillFiles().map((f) => ({ path: f.path, read: () => readFile(f.source, "utf-8") }));
+    const theirs = [
+        { path: "AGENTS.md", read: async () => agentsMd(siteName) },
+        { path: "CLAUDE.md", read: async () => claudeMd() },
+    ];
+    const files = [];
+    for (const file of ours) {
+        const next = await file.read();
+        const current = await readIfPresent(join(dir, file.path));
+        if (current === next) {
+            files.push({ path: file.path, outcome: "unchanged" });
+            continue;
+        }
+        if (!dryRun)
+            await write(join(dir, file.path), next);
+        files.push({ path: file.path, outcome: current === null ? "created" : "updated" });
+    }
+    // What an agent will actually read after this run: the file we kept, or the
+    // one we wrote. Either can carry the pointer, so both are checked together.
+    const effective = [];
+    for (const file of theirs) {
+        const current = await readIfPresent(join(dir, file.path));
+        if (current !== null) {
+            effective.push(current);
+            files.push({ path: file.path, outcome: "kept" });
+            continue;
+        }
+        const next = await file.read();
+        effective.push(next);
+        if (!dryRun)
+            await write(join(dir, file.path), next);
+        files.push({ path: file.path, outcome: "created" });
+    }
+    return {
+        files,
+        created: files.filter((f) => f.outcome === "created").length,
+        updated: files.filter((f) => f.outcome === "updated").length,
+        unchanged: files.filter((f) => f.outcome === "unchanged").length,
+        kept: files.filter((f) => f.outcome === "kept").length,
+        pointerMissing: !effective.some((body) => body.includes("avocado")),
+    };
+}
+async function readIfPresent(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+async function write(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf-8");
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@avocadostudio-ai/skills",
+  "version": "0.14.0",
+  "description": "Install Avocado Studio's agent skills into a project, so a coding agent reads instructions that match the version you have",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "avocado-skills": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "agent-skills",
+    "claude",
+    "agents",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://docs.avocadostudio.dev",
+  "bugs": {
+    "url": "https://docs.avocadostudio.dev"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "NODE_ENV=test node ../../scripts/run-tests.mjs"
+  }
+}

package/skills/avocado/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: avocado
+description: Wire Avocado Studio into a website, or work on a site that already has it — chat-driven content editing with live preview, running on the user's own Next.js or Astro app. Use when asked to add, integrate, set up, debug or extend Avocado Studio, @avocadostudio-ai/* packages, the editor API, the orchestrator, blocks, or the live preview.
+---
+
+# Avocado Studio
+
+Avocado adds chat-driven content editing to a site the user already owns. It is
+not a CMS and not a hosting platform: it runs in their app, on their key, and
+edits their content in place.
+
+**Read this file first, then load exactly one of the task skills below.** Do not
+try to do the work from this page — it deliberately holds only what is true on
+every path.
+
+## Pick the path
+
+| The user has | Load |
+|---|---|
+| A Next.js app that already exists, with its own components and content | `avocado-integrate` |
+| Nothing yet, or wants to see it working before committing | `avocado-demo` |
+| Either, and you are now declaring their components as editable blocks | `avocado-blocks` |
+
+Before deciding, if the site is live, `npx avocado-scope <url>` will tell you
+what one of its pages would become as blocks without installing or writing
+anything. It is read-only, deterministic and free.
+
+If it is ambiguous, ask one question: *"Is this going onto a site you already
+have, or do you want a demo first?"* Do not guess — the two paths write
+different files, and the integrate path must not overwrite a page the user
+wrote.
+
+## The one rule that shapes everything
+
+**A component's props are not editable until they are declared.** Avocado can
+only change what a registered schema names. An undeclared prop is unreachable by
+any operation, any prompt and any model. Declaring less is the conservative
+choice and adding a field later is one line.
+
+This is why "just let the agent edit the code" is the wrong shape for content
+work, and it is the whole safety story. Do not route around it — never write an
+operation that pokes at an undeclared prop, and never widen a schema to make an
+edit go through without telling the user.
+
+## Rules that hold on every path
+
+- **Install with the package manager the project already uses.** The lockfile
+  says which. Do not introduce a second one.
+- **Import only from `@avocadostudio-ai/site-sdk`.** `registerBlock` and `z`
+  come from `@avocadostudio-ai/site-sdk/blocks`; the attribute helpers from
+  `@avocadostudio-ai/site-sdk/markers`. Never import `@avocadostudio-ai/shared`,
+  `@avocadostudio-ai/blocks`, `@avocadostudio-ai/preview-adapter` or a bare
+  `zod` from the user's source. Under pnpm they will not resolve; under npm's
+  flat hoisting they resolve today and break the first time something
+  re-hoists, and two copies of zod fail in ways that look like schema bugs.
+- **Never import from `@avocadostudio-ai/site-sdk/editor` in anything a public
+  page renders.** That entry also exports `EditorOverlay` and the live-preview
+  provider, so a `'use client'` component reaching there for a two-line
+  attribute helper drags the whole editor into the public bundle — measured at
+  +66 kB First Load JS for byte-identical markup. Use `/markers`.
+- **Do not hand-write the editor routes.** `createEditorApiHandler` serves all
+  five endpoints and they are security-critical: it validates `?secret=`
+  against `DRAFT_MODE_SECRET`, refuses non-internal redirects, sets the draft
+  cookie, answers CORS preflight, and refuses a publish that would delete every
+  page.
+- **`PUBLISH_TOKEN` is not optional in production.** `/api/editor/publish`
+  overwrites the site's content. With no `publishSecret` configured it answers
+  401 and names the variable rather than running open.
+- **Wrap the Next config.** `withAvocado` from
+  `@avocadostudio-ai/site-sdk/next-config` sets `transpilePackages`,
+  `serverExternalPackages`, the matching server externals and
+  `skipTrailingSlashRedirect` together. Setting one of them by hand looks right
+  and fails quietly on the native dependencies.
+- **Finish on a number, not on "it builds."** Every path ends with a
+  verification step that produces a count. Report it.
+
+## Versions
+
+Install the packages without pinning a version and let the registry resolve —
+`@avocadostudio-ai/*` ship in lockstep, so a mixed tree is the one failure mode
+worth avoiding. If you must pin, pin every one of them to the same version.
+
+## When you are stuck
+
+`https://docs.avocadostudio.dev/llms.txt` indexes the full documentation. Fetch
+the page you need rather than guessing an API. If a symbol is not in the
+published `exports` map it is not reachable from a registry install, however
+well it resolves in a workspace.

package/skills/avocado-blocks/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: avocado-blocks
+description: Declare a site's React components as Avocado blocks — registerBlock schemas, field kinds, list fields, and the data-editable-target markup the editor needs to address a field. Use when wiring custom or existing components into Avocado Studio, or when the property panel shows the wrong control or nothing at all.
+---
+
+# Declaring components as blocks
+
+Read the `avocado` skill first — the import rules there apply to every line
+below.
+
+A block is one of the user's components plus a schema saying which of its props
+are content. The schema is the safety boundary: an undeclared prop cannot be
+reached by any operation, prompt or model.
+
+## The registration
+
+```ts
+// avocado/blocks.ts
+import { registerBlock, z } from "@avocadostudio-ai/site-sdk/blocks"
+
+export function registerBlocks() {
+  registerBlock("PricingTier", {
+    schema: z.object({
+      name: z.string(),
+      price: z.string(),
+      blurb: z.string(),
+      tiers: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+    }),
+    meta: {
+      displayName: "Pricing Tier",
+      fields: { name: { kind: "text" }, price: { kind: "text" }, blurb: { kind: "richtext" } },
+      listFields: {
+        tiers: { itemFields: { label: { kind: "text" }, value: { kind: "text" } } },
+      },
+    },
+  })
+}
+```
+
+Four things that are each a compile error or a silent defect if you get them
+wrong:
+
+1. **The type is the first argument**, not a `type:` key. The signature is
+   `registerBlock(type: string, config: { schema, meta })`.
+2. **`fields` lives under `meta`**, never at the top level.
+3. **`meta.displayName` is required.** It is what the user sees in the panel.
+4. **Array props go in `meta.listFields` with an `itemFields` map**, not in
+   `meta.fields`, which is for scalars only. A list declared as a scalar reaches
+   the panel as nothing at all.
+
+Then hand the function to the handler rather than relying on import side
+effects — Next's dev bundler does not honour source-order side effects across
+RSC / SSR / route layers, and a late canonical registration can silently clobber
+the site's:
+
+```ts
+export const { GET, POST, OPTIONS } = createEditorApiHandler({
+  getPages,
+  registerBlocks,
+  blockTypes: ["PricingTier", "LogoWall"],   // narrow the manifest to what this site renders
+  onPublish,
+  publishSecret: process.env.PUBLISH_TOKEN?.trim() || undefined,
+})
+```
+
+## Field kinds
+
+| The prop holds | kind |
+|---|---|
+| A short string | `text` |
+| A document the user edits as prose | `richtext` |
+| **A string of markup** rendered with `dangerouslySetInnerHTML` | `html` |
+| An image path or URL | `image` |
+| A list of plain strings | `stringList` |
+| A list of images | `imageList` |
+
+`richtext` and `html` are the one people get wrong. `richtext` means a
+*document*. Declare a markup string as `richtext` and the panel renders the tags
+literally, as visible `<span class="…">` text nobody can edit without breaking
+it, and writes whatever they type over it. `html` round-trips through the same
+editor and preserves the elements and attributes it cannot model.
+
+Declare presentation props — variants, spacing, feature flags — **nowhere**. If
+it is not content, leaving it out is the point.
+
+## Names that collide with the built-ins
+
+Avocado ships twenty built-in types: `Hero`, `FeatureGrid`, `Testimonials`,
+`FAQAccordion`, `CTA`, `Card`, `CardGrid`, `RichText`, `Banner`, `Carousel`,
+`Embed`, `Footer`, `Gallery`, `Quote`, `SiteHeader`, `Stats`, `Table`, `Tabs`,
+`TwoColumn`, `Video`.
+
+- **Inventing a new block** under one of those names: don't. Prefix the type and
+  keep the component name as it is.
+- **Existing content that already uses the name**: register over it. Renaming
+  the type means rewriting every stored page, and `registerBlock("Hero", …)`
+  deliberately replaces the built-in definition — its schema *and* its built-in
+  flag — with the site's. Then pass `blockTypes` naming only the types this site
+  renders, so the manifest stops advertising built-ins nobody implemented. Tell
+  the user which names were replaced.
+
+## Marking up the renderer
+
+A declared field is editable in the panel. It is editable **in the preview**
+only once the element that renders it carries a marker:
+
+```tsx
+import { editableProps } from "@avocadostudio-ai/site-sdk/markers"
+
+export function PricingTier({ blockId, name, blurb }) {
+  return (
+    <section>
+      <h3 {...editableProps(blockId, "name")}>{name}</h3>
+      <p {...editableProps(blockId, "blurb")}>{blurb}</p>
+    </section>
+  )
+}
+```
+
+Import from `/markers`, never from `/editor` — see the rule in the `avocado`
+skill about the public bundle.
+
+Two things this costs on a real site, so plan for them: subcomponents factored
+for rendering often do not know their own position and need a path argument
+threaded in, and the marker has to go on the element that actually renders the
+text, not its wrapper.
+
+## Verify on a number
+
+`@avocadostudio-ai/site-sdk/coverage` measures which declared fields a rendered
+page actually marks. Run it and report the figure. "It builds" is not a result:
+a site can build perfectly with every field unreachable.
+
+Cross-check the manifest directly too — `GET /api/editor/blocks` should list
+exactly the site's types, with the expected `fields` and `listFields` on each.

package/skills/avocado-demo/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: avocado-demo
+description: Stand up a working Avocado Studio demo — a JSON-backed Next.js page editable by chat, in one sitting, with no CMS and no repository to clone. Use when the user wants to see Avocado working before committing to an integration, or is starting from an empty directory.
+---
+
+# A demo you can edit by talking to it
+
+Read the `avocado` skill first. This path creates a small, complete, runnable
+site: a JSON file, two built-in blocks, the orchestrator mounted in the app.
+
+It is a *demo*. Do not run it against a site the user cares about — for that,
+load `avocado-integrate`.
+
+The fastest route is the scaffolder, which does all of the below and installs:
+
+```bash
+npm create avocado-site@latest
+```
+
+Use it unless the user explicitly wants the wiring written into a project they
+already created. The rest of this page is that wiring.
+
+## Wire it
+
+Starting from an empty directory, create the app first:
+
+```bash
+npx create-next-app@latest . --ts --app --tailwind --eslint \
+  --no-src-dir --import-alias "@/*" --use-npm --yes
+npm install @avocadostudio-ai/site-sdk @avocadostudio-ai/orchestrator-core
+```
+
+Then:
+
+1. **`rm app/page.tsx`.** `create-next-app` leaves a starter page there. It
+   matches `/` more specifically than the catch-all below, so leaving it means
+   the site is the Next.js starter and nothing anywhere says why.
+
+2. **`next.config.ts`** — `export default withAvocado({})` from
+   `@avocadostudio-ai/site-sdk/next-config`.
+
+3. **`app/globals.css`** — `@import "@avocadostudio-ai/blocks/styles.css";` as
+   the **first** line. Without it the page renders, and renders unstyled.
+
+4. **`content/pages.json`** — one page `{ id, slug: "/", title, updatedAt,
+   blocks: [] }` with a `Hero` (props: `heading`, `subheading`, `ctaText`,
+   `ctaHref`) and a `CTA` (props: `title`, `description`, `ctaText`,
+   `ctaHref`). Both are built-in types, so nothing needs registering.
+
+5. **`lib/content.ts`** — `getPage(slug)`, `getSlugs()`, `getPages()` reading
+   that JSON, plus `getSiteConfig()` returning a literal like
+   `{ name: "My Site" }`: the file holds pages and has nowhere to put site
+   config. Types `PageDoc` and `SiteConfig` come from
+   `@avocadostudio-ai/site-sdk`.
+
+6. **`app/api/editor/[...path]/route.ts`** — `createEditorApiHandler` from
+   `@avocadostudio-ai/site-sdk/routes`, with `getPages`,
+   `onPublish: createJsonFilePublishHandler(resolve(process.cwd(), "content/pages.json"))`
+   from `@avocadostudio-ai/site-sdk/publish-handlers/json-file`, and
+   `publishSecret: process.env.PUBLISH_TOKEN?.trim() || undefined`.
+
+7. **`app/api/avocado/[[...path]]/route.ts`** — `createOrchestrator` from
+   `@avocadostudio-ai/site-sdk/server` with `jsonFileAdapter` from
+   `@avocadostudio-ai/orchestrator-core/cms` pointed at the same JSON file and
+   passed **`writeOnPublish: true`**. It defaults to `false`, which leaves the
+   adapter with no `onPublish` — and Publish then reports success and writes
+   nothing. Add `export const runtime = "nodejs"` and
+   `export const dynamic = "force-dynamic"`, and assign the single returned
+   handler to `GET`, `POST` and `OPTIONS` rather than destructuring it.
+
+8. **`app/[[...slug]]/page.tsx`** — `createSitePage` from
+   `@avocadostudio-ai/site-sdk/page` with `siteId`, `siteName`, `getPage`,
+   `getSlugs`, `getSiteConfig`, and
+   `siteUrl: process.env.NEXT_PUBLIC_SITE_URL`. Export `default Page` **and**
+   `export { generateStaticParams, generateMetadata }`.
+
+   The `siteId` must be the same string as step 7's, or the page asks for a
+   draft session the orchestrator never seeded.
+
+9. **`.gitignore`** — add `.data/`. The orchestrator writes its SQLite state
+   there on the first request and `create-next-app`'s ignore file does not cover
+   it, so the first `git add .` otherwise commits a database.
+
+10. **`.env.local`** — one LLM key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or
+    `GOOGLE_GENAI_API_KEY`), `ORCHESTRATOR_URL=http://localhost:3000/api/avocado`,
+    `NEXT_PUBLIC_SITE_URL=http://localhost:3000`, and generated values for
+    `DRAFT_MODE_SECRET` and `PUBLISH_TOKEN`.
+
+    A Gemini key also needs `@google/genai` installed: it is an optional peer of
+    `orchestrator-core`, loaded lazily, so no package manager installs it and a
+    Gemini plan fails at the first call without it.
+
+## Verify
+
+`npm run build`, serve it, and check the bytes rather than the console:
+
+- the page's own `<title>` and `<meta name="description">`, not the layout's
+- the hero `<h1>`, carrying a `data-editable-target` attribute
+- a `<link rel="canonical">` and `og:url` — these are what `siteUrl` turns on
+- the blocks stylesheet linked
+- an unknown slug answering a real **404**, not 200
+
+Note that `next start` runs with `NODE_ENV=production`, where library mode
+refuses every request unless a credential is set — `/api/avocado/auth/status`
+reporting `mode: "closed"` there is correct, not a failure. Chat editing is a
+`npm run dev` activity until the user configures `ACCESS_PASSWORD_HASH` or
+`ORCHESTRATOR_ACCESS_TOKEN`.

package/skills/avocado-integrate/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: avocado-integrate
+description: Wire Avocado Studio into a Next.js site that already exists — its own components, its own content or CMS, its own routes. Use when adding chat-driven editing to a real site rather than scaffolding a demo.
+---
+
+# Adding Avocado to a site that already exists
+
+Read the `avocado` skill first. This path edits a site somebody built and cares
+about: **survey before you write anything, and never overwrite a file the user
+wrote without saying so.**
+
+Work on a branch. Produce a diff the user reviews.
+
+## 1. Survey, and report before touching anything
+
+Answer these from the repo, not from assumption, and tell the user the answers:
+
+- **Next version and router.** 15 or 16; App Router or Pages. Pages Router is
+  not supported — stop and say so.
+- **Where content lives.** A JSON file, a local CMS module, Contentful, Sanity,
+  Strapi, Storyblok, something bespoke. Name the module that reads it.
+- **What renders a page today.** Usually a catch-all route plus a renderer that
+  switches on a block/section type. Name both files.
+- **Which components are content-bearing**, and what their props are called.
+- **Which route files exist**, and which of them serve URLs the content also
+  describes.
+- **The package manager**, from the lockfile.
+
+If the site already renders from a list of typed sections with props, this is a
+short job. If content is embedded in JSX, it is a long one — say that before
+starting, not halfway through.
+
+If the site is reachable at a URL, run `npx avocado-scope <url>` on two or
+three of its pages first. It reports how many sections each page has and what
+each would become as blocks, without installing or writing anything, and it is
+the fastest way to tell the user how large this job is before agreeing to it. A
+page that comes back mostly `RichText` is telling you its structure lives in
+JSX rather than in data.
+
+## 2. Install and mount
+
+```bash
+npm install @avocadostudio-ai/site-sdk    # or the project's own manager
+```
+
+Add `@avocadostudio-ai/orchestrator-core` as well if the orchestrator is to run
+inside this app ("library mode") rather than as a separate process.
+
+**Wrap the Next config.** Whatever shape it is in — `next.config.ts`,
+`next.config.js`, ESM or CommonJS — wrap the existing exported object; do not
+create a second config file beside it:
+
+```ts
+import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
+export default withAvocado(existingConfig)
+```
+
+**The editor API, as one catch-all route** at
+`app/api/editor/[...path]/route.ts`:
+
+```ts
+import { createEditorApiHandler } from "@avocadostudio-ai/site-sdk/routes"
+import { getPages, publishPages } from "@/lib/my-cms"
+import { registerBlocks } from "@/avocado/blocks"
+
+export const { GET, POST, OPTIONS } = createEditorApiHandler({
+  getPages: () => getPages(),
+  registerBlocks,
+  blockTypes: ["PricingTier", "LogoWall"],
+  onPublish: async (pages, config) => { await publishPages(pages, config); return { ok: true } },
+  publishSecret: process.env.PUBLISH_TOKEN?.trim() || undefined,
+})
+```
+
+**Library mode**, if the orchestrator runs in this app, at
+`app/api/avocado/[[...path]]/route.ts`:
+
+```ts
+import { createOrchestrator } from "@avocadostudio-ai/site-sdk/server"
+
+export const runtime = "nodejs"
+export const dynamic = "force-dynamic"
+
+const handler = createOrchestrator({ adapter, siteId: "…", siteName: "…" })
+export const POST = handler
+export const GET = handler
+export const OPTIONS = handler
+```
+
+`createOrchestrator` returns one callable — assign it three times rather than
+destructuring it. Point `ORCHESTRATOR_URL` at this mount
+(`http://localhost:3000/api/avocado`); the default is a standalone orchestrator
+on `:4200`, and when something else is listening there the preview silently
+renders that process's content.
+
+**The request rewrite:** Next 15 uses `middleware.ts` with
+`createEditorMiddleware` from `@avocadostudio-ai/site-sdk/middleware`; Next 16
+uses `proxy.ts` with `createEditorProxy` from
+`@avocadostudio-ai/site-sdk/proxy`, and its `config` must be a static object
+literal.
+
+## 3. Declare the components
+
+Load `avocado-blocks` and follow it. On an existing site the block names are
+usually already decided by the stored content, which is the case that skill's
+"names that collide with the built-ins" section is about.
+
+## 4. Decide about the page route — carefully
+
+`createSitePage` from `@avocadostudio-ai/site-sdk/page` is a full page factory:
+it renders registered blocks, supplies `generateStaticParams` and
+`generateMetadata`, and calls `notFound()` for an unknown slug.
+
+**It replaces whatever renders pages today.** On a site with its own renderer
+that is a real decision, not a step:
+
+- *Keep the site's renderer* when it does layout the blocks do not — wrappers,
+  section chrome, per-page composition. The editor works fine against it; what
+  matters is the markers, not who renders them.
+- *Adopt `createSitePage`* when the existing catch-all is thin and the site
+  gains metadata, canonical and Open Graph handling it did not have.
+
+Ask before replacing. If you do adopt it, export all three symbols — without
+`generateMetadata` every page inherits the root layout's title and ships no
+description — and pass `siteUrl` from the environment, which is what turns on
+the canonical link, `og:url`, and an absolute `og:image`.
+
+Then **delete or move every route file whose content now comes from `getPage`**.
+A more specific route keeps winning, Next reports no conflict and logs nothing,
+so those URLs go on serving the old component and the integration looks dead
+while being perfectly wired. List every route removed and every one left, with
+the reason.
+
+## 5. Keep the public bundle clean
+
+Import the attribute helpers from `@avocadostudio-ai/site-sdk/markers`. Check
+the First Load JS before and after: an unchanged number is the expected result.
+If it jumped by tens of kilobytes, something on a public page imported from
+`/editor`.
+
+## 6. Verify on numbers
+
+Do all of these and report the figures:
+
+1. `next build` succeeds, and the route list still shows the site's own pages.
+2. `GET /api/editor/blocks` lists exactly the site's types, with the expected
+   `fields` and `listFields`.
+3. The field coverage figure from `@avocadostudio-ai/site-sdk/coverage`.
+4. A page still renders the site's own markup — diff the HTML against the
+   pre-integration build if you can.
+5. An unknown slug still answers a real 404.
+
+## What not to do
+
+- Do not overwrite the user's `next.config`, page route or `globals.css`
+  wholesale. Wrap, extend, or ask.
+- Do not rename stored block types to avoid a collision. Register over the name.
+- Do not declare presentation props to make something editable.
+- Do not add `allowDelete` to get past the publish guard.
+- Do not report success on "it builds."