@introspection-ai/pi-recipes 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -13,7 +13,7 @@ those recipe files into the live Pi session at launch time.
 `package.json` owns both recipe identity and Node dependency metadata. The
 top-level `name`, `version`, and `description` identify the recipe, while the
 `pi` block declares recipe resources such as agents, extensions, skills,
-prompts, and themes.
+and prompts.
 
 ## Documentation
 
@@ -88,6 +88,10 @@ repository and pushes the local recipe:
 recipes publish ./my-recipe --github owner/my-recipe --visibility private
 ```
 
+Use `--visibility public` to submit the recipe's public GitHub metadata to the
+marketplace catalog after a successful push. Catalog submissions are
+best-effort; private publishes are not listed.
+
 Customize an installed recipe into an editable local copy:
 
 ```bash

package/dist/cli.js

@@ -274,6 +274,7 @@ function printPublishedRecipe(result) {
         `Repository: ${result.createdRepository ? "created" : "existing"}`,
         `Commit: ${result.committed ? "created" : "no changes"}`,
         "Push: ok",
+        `Catalog: ${result.catalogued ? "submitted" : "skipped"}`,
         "",
         "Use:",
         `  pi --recipe ${result.shortName}`,

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from "./recipe-dev.js";
 export * from "./recipe-package.js";
 export * from "./recipe-publish.js";
 export * from "./recipe-store.js";
+export * from "./recipe-telemetry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,4 +4,5 @@ export * from "./recipe-dev.js";
 export * from "./recipe-package.js";
 export * from "./recipe-publish.js";
 export * from "./recipe-store.js";
+export * from "./recipe-telemetry.js";
 //# sourceMappingURL=index.js.map

package/dist/pi-extension.js

@@ -481,7 +481,6 @@ export function createPiRecipesExtension(opts = {}) {
             agent: resolved.agent,
             skillPaths: packageResourcePaths(manifest, "skills"),
             promptPaths: packageResourcePaths(manifest, "prompts"),
-            themePaths: packageResourcePaths(manifest, "themes"),
             extensionPaths,
             extensionsLoaded: false,
             configured: false,
@@ -791,7 +790,6 @@ export function createPiRecipesExtension(opts = {}) {
             return {
                 skillPaths: launchState.skillPaths,
                 promptPaths: launchState.promptPaths,
-                themePaths: launchState.themePaths,
             };
         });
         pi.on("before_agent_start", (event, ctx) => {

package/dist/recipe-agent.js

@@ -37,13 +37,12 @@ function parseModel(data) {
 }
 function parseSystemInstructions(data) {
     const raw = asRecord(data.system_instructions ?? data.systemInstructions);
-    const content = typeof raw.content === "string" ? raw.content.trim() : "";
-    if (!content) {
-        const prompt = typeof data.prompt === "string" ? data.prompt.trim() : "";
-        return prompt ? { mode: "append", content: prompt } : undefined;
+    if (Object.hasOwn(raw, "content") && typeof raw.content === "string") {
+        const mode = raw.mode === "replace" ? "replace" : "append";
+        return { mode, content: raw.content.trim() };
     }
-    const mode = raw.mode === "replace" ? "replace" : "append";
-    return { mode, content };
+    const prompt = typeof data.prompt === "string" ? data.prompt.trim() : "";
+    return prompt ? { mode: "append", content: prompt } : undefined;
 }
 function parseExtensions(data) {
     const raw = asRecord(data.extensions);

package/dist/recipe-dev.js

@@ -7,7 +7,6 @@ const RESOURCE_KEYS = [
     "extensions",
     "skills",
     "prompts",
-    "themes",
 ];
 function recipeNameFromTarget(target) {
     const name = basename(resolve(target)).replace(/[^a-zA-Z0-9._-]+/g, "-");
@@ -165,7 +164,7 @@ export function createRecipePublishGuide(recipeDir) {
         checklist: [
             "Run `recipes doctor .` and fix any errors.",
             `Run \`recipes publish . --github owner/${repositoryName} --visibility private\` to create, commit, and push a GitHub repository.`,
-            "Commit package.json, agents, prompts, skills, themes, extensions, and SYSTEM.md.",
+            "Commit package.json, agents, prompts, skills, extensions, and SYSTEM.md.",
             "If extensions have runtime dependencies, commit the package lockfile.",
             "Push the recipe to a Git repository.",
             "Tag releases when users should install a stable version.",

package/dist/recipe-package.d.ts

@@ -3,7 +3,6 @@ export interface RecipePackageResources {
     extensions: string[];
     skills: string[];
     prompts: string[];
-    themes: string[];
 }
 export interface RecipePackageManifest {
     name: string;

package/dist/recipe-package.js

@@ -5,7 +5,6 @@ const RESOURCE_KEYS = [
     "extensions",
     "skills",
     "prompts",
-    "themes",
 ];
 function stringArray(value) {
     return Array.isArray(value)
@@ -18,7 +17,6 @@ function emptyResources() {
         extensions: [],
         skills: [],
         prompts: [],
-        themes: [],
     };
 }
 function normalizeResourcePath(path) {
@@ -196,7 +194,6 @@ export function defaultPiPackageResourcePaths(pkg, key) {
         agents: [join(pkg.path, "agents")],
         skills: [join(pkg.path, "skills")],
         prompts: [join(pkg.path, "prompts")],
-        themes: [join(pkg.path, "themes")],
     };
     return (defaults[key] ?? []).filter((path) => existsSync(path));
 }
@@ -205,8 +202,7 @@ export function packageResourcePaths(pkg, key) {
         return resolvePiPackageResourcePaths(pkg, key, {
             allowEmptyGlobMatches: key === "extensions" ||
                 key === "skills" ||
-                key === "prompts" ||
-                key === "themes",
+                key === "prompts",
         });
     }
     return defaultPiPackageResourcePaths(pkg, key);

package/dist/recipe-publish.d.ts

@@ -25,6 +25,7 @@ export interface PublishedRecipe {
     createdRepository: boolean;
     committed: boolean;
     pushed: boolean;
+    catalogued: boolean;
 }
 export declare function publishRecipe(target: string, opts: RecipePublishOptions): Promise<PublishedRecipe>;
 //# sourceMappingURL=recipe-publish.d.ts.map

package/dist/recipe-publish.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { validateRecipeDirectory } from "./recipe-dev.js";
 import { readPiPackageManifest } from "./recipe-package.js";
 import { addRecipe, customizeRecipe, defaultRecipeStoreDir, findInstalledRecipe, recipePreferredIdentifier, recipeScopedIdentifier, } from "./recipe-store.js";
+import { sendPublishTelemetry, telemetryDisabled } from "./recipe-telemetry.js";
 const execFileAsync = promisify(execFile);
 function isSafeGithubName(value) {
     return /^[a-zA-Z0-9_.-]+$/.test(value) && value !== "." && value !== "..";
@@ -82,6 +83,14 @@ function ensureGitignore(recipeDir) {
     writeFileSync(gitignorePath, `${existing.join("\n").replace(/\n*$/, "")}${prefix}${missing.join("\n")}\n`);
     return true;
 }
+function resourceCounts(resources) {
+    return {
+        agents: resources.agents?.length ?? 0,
+        extensions: resources.extensions?.length ?? 0,
+        skills: resources.skills?.length ?? 0,
+        prompts: resources.prompts?.length ?? 0,
+    };
+}
 function localPathForInput(input, cwd) {
     const expanded = input === "~"
         ? process.env.HOME ?? input
@@ -176,7 +185,23 @@ export async function publishRecipe(target, opts) {
     const createdRepository = await ensureGithubRepository(github, opts.visibility, recipeDir, env, opts.commandRunner);
     await setOrigin(github, recipeDir, env, opts.commandRunner);
     await runCommand("git", ["push", "-u", "origin", "HEAD:main"], { cwd: recipeDir, env }, opts.commandRunner);
+    const publishedManifest = readPiPackageManifest(recipeDir);
     const recipe = await addRecipe(recipeDir, opts);
+    const catalogued = opts.visibility === "public" && !telemetryDisabled(env);
+    if (catalogued) {
+        const source = `github:${github.fullName}`;
+        await sendPublishTelemetry({
+            id: source,
+            name: publishedManifest.name,
+            version: publishedManifest.version,
+            ...(publishedManifest.description ? { description: publishedManifest.description } : {}),
+            github: github.fullName,
+            source,
+            installCommand: `recipes install ${source}`,
+            homepage: `https://github.com/${github.fullName}`,
+            resources: resourceCounts(report.resources),
+        }, { env: opts.env, fetchImpl: opts.fetchImpl });
+    }
     return {
         recipe,
         recipeDir,
@@ -187,6 +212,7 @@ export async function publishRecipe(target, opts) {
         createdRepository,
         committed,
         pushed: true,
+        catalogued,
     };
 }
 //# sourceMappingURL=recipe-publish.js.map

package/dist/recipe-store.d.ts

@@ -1,7 +1,9 @@
+import { type FetchImpl } from "./recipe-telemetry.js";
 export interface RecipeStoreOptions {
     storeDir?: string;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchImpl;
 }
 export interface InstalledRecipe {
     id: string;

package/dist/recipe-store.js

@@ -5,6 +5,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:pat
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readPiPackageManifest, validatePiPackageManifest, } from "./recipe-package.js";
+import { sendInstallTelemetry } from "./recipe-telemetry.js";
 const execFileAsync = promisify(execFile);
 const STORE_LOCK_STALE_MS = 30_000;
 const STORE_LOCK_TIMEOUT_MS = 10_000;
@@ -602,6 +603,11 @@ export async function addRecipe(input, opts = {}) {
         ].sort((a, b) => a.name.localeCompare(b.name));
         writeRecipeStore(store, storeDir);
     });
+    // Anonymous, best-effort install ping for the public directory. Only remote
+    // (github/git) installs are counted; local recipe registration is private.
+    if (source.kind === "github" || source.kind === "git") {
+        await sendInstallTelemetry(installed, { env: opts.env, fetchImpl: opts.fetchImpl });
+    }
     return installed;
 }
 export function listRecipes(opts = {}) {

package/dist/recipe-telemetry.d.ts

@@ -0,0 +1,44 @@
+import type { InstalledRecipe } from "./recipe-store.js";
+import type { RecipePackageResources } from "./recipe-package.js";
+export declare const DEFAULT_TELEMETRY_ENDPOINT = "https://pi.recipes/api/installs";
+export declare const DEFAULT_CATALOG_ENDPOINT = "https://pi.recipes/api/catalog/recipes";
+export type FetchImpl = typeof fetch;
+export interface InstallTelemetryOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchImpl;
+}
+export interface PublishTelemetryOptions extends InstallTelemetryOptions {
+    endpoint?: string;
+}
+export interface PublishTelemetryRecipe {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    github: string;
+    source: string;
+    installCommand: string;
+    homepage: string;
+    resources: Record<keyof RecipePackageResources, number>;
+}
+/**
+ * Returns true when the user has opted out of recipe telemetry.
+ * Honors the cross-tool `DO_NOT_TRACK` convention plus a package-specific
+ * `PI_RECIPES_NO_TELEMETRY` escape hatch.
+ */
+export declare function telemetryDisabled(env: NodeJS.ProcessEnv): boolean;
+export declare function telemetryEndpoint(env: NodeJS.ProcessEnv): string;
+export declare function catalogEndpoint(env: NodeJS.ProcessEnv): string;
+/**
+ * Send a single anonymous install ping. Resolves once the request settles or
+ * the timeout elapses; all network and serialization errors are swallowed so a
+ * telemetry failure can never break `recipes install`.
+ */
+export declare function sendInstallTelemetry(recipe: InstalledRecipe, opts?: InstallTelemetryOptions): Promise<void>;
+/**
+ * Submit a public recipe for marketplace cataloguing. The backend owns
+ * trust/moderation fields such as `official`; clients submit only public
+ * package metadata derived from the GitHub repository and recipe manifest.
+ */
+export declare function sendPublishTelemetry(recipe: PublishTelemetryRecipe, opts?: PublishTelemetryOptions): Promise<void>;
+//# sourceMappingURL=recipe-telemetry.d.ts.map

package/dist/recipe-telemetry.js

@@ -0,0 +1,79 @@
+// Best-effort telemetry for the recipes directory at https://pi.recipes.
+// Installs send only anonymous counters. Public publishes submit public package
+// metadata so the directory can catalogue recipes. Telemetry never blocks or
+// fails a recipe command.
+export const DEFAULT_TELEMETRY_ENDPOINT = "https://pi.recipes/api/installs";
+export const DEFAULT_CATALOG_ENDPOINT = "https://pi.recipes/api/catalog/recipes";
+const TELEMETRY_TIMEOUT_MS = 1500;
+/**
+ * Returns true when the user has opted out of recipe telemetry.
+ * Honors the cross-tool `DO_NOT_TRACK` convention plus a package-specific
+ * `PI_RECIPES_NO_TELEMETRY` escape hatch.
+ */
+export function telemetryDisabled(env) {
+    return isTruthy(env.DO_NOT_TRACK) || isTruthy(env.PI_RECIPES_NO_TELEMETRY);
+}
+export function telemetryEndpoint(env) {
+    const configured = env.PI_RECIPES_TELEMETRY_ENDPOINT?.trim();
+    return configured && configured.length > 0 ? configured : DEFAULT_TELEMETRY_ENDPOINT;
+}
+export function catalogEndpoint(env) {
+    const configured = env.PI_RECIPES_CATALOG_ENDPOINT?.trim();
+    return configured && configured.length > 0 ? configured : DEFAULT_CATALOG_ENDPOINT;
+}
+/**
+ * Send a single anonymous install ping. Resolves once the request settles or
+ * the timeout elapses; all network and serialization errors are swallowed so a
+ * telemetry failure can never break `recipes install`.
+ */
+export async function sendInstallTelemetry(recipe, opts = {}) {
+    await postTelemetry(telemetryEndpoint(opts.env ?? process.env), {
+        event: "install",
+        id: recipe.id,
+        name: recipe.name,
+        version: recipe.version,
+    }, opts);
+}
+/**
+ * Submit a public recipe for marketplace cataloguing. The backend owns
+ * trust/moderation fields such as `official`; clients submit only public
+ * package metadata derived from the GitHub repository and recipe manifest.
+ */
+export async function sendPublishTelemetry(recipe, opts = {}) {
+    const env = opts.env ?? process.env;
+    await postTelemetry(opts.endpoint ?? catalogEndpoint(env), {
+        event: "publish",
+        ...recipe,
+    }, opts);
+}
+async function postTelemetry(endpoint, body, opts) {
+    const env = opts.env ?? process.env;
+    if (telemetryDisabled(env))
+        return;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function")
+        return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+    try {
+        await fetchImpl(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Telemetry is best-effort. Never surface failures to the caller.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function isTruthy(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+//# sourceMappingURL=recipe-telemetry.js.map

package/docs/pi-extension.md

@@ -84,7 +84,7 @@ On session startup, the extension:
 6. Sets the Pi session name.
 7. Sets the model and thinking level from the selected agent when specified.
 8. Selects active tools from the selected agent.
-9. Returns recipe resources for skills, prompts, and themes.
+9. Returns recipe resources for skills and prompts.
 10. Composes the runtime system prompt from Pi defaults, `SYSTEM.md`, selected agent instructions, and recipe runtime context.
 
 The current Pi working directory remains the user's project workspace. The
@@ -102,7 +102,7 @@ The `pi` block tells Pi which recipe-owned files should be loaded:
 
 - agent definition globs
 - extension globs
-- skill, prompt, and theme paths
+- skill and prompt paths
 
 The same file also carries normal Node package metadata for extension
 dependencies. Add `dependencies`, `peerDependencies`, `packageManager`, and a
@@ -171,6 +171,9 @@ Objects such as `model` and `extensions` merge by key. Arrays such as `tools`,
 - `append`: append to the current prompt
 - `replace`: replace the current prompt
 
+Use `content: ""` when an agent intentionally adds no instructions beyond
+`SYSTEM.md` but still needs to declare the field explicitly.
+
 ## Session Prompt
 
 The session prompt is assembled from:
@@ -233,7 +236,7 @@ When a recipe is active, the extension registers:
 - recipe directory
 - project workspace
 
-`/recipe reload` asks Pi to reload extensions, skills, prompts, and themes, and
+`/recipe reload` asks Pi to reload extensions, skills, and prompts, and
 clears the cached recipe manifest and agent state first. Use it after editing a
 local recipe's `package.json`, agent files, resources, or extension code.
 
@@ -243,17 +246,15 @@ The extension responds to Pi `resources_discover` with:
 
 - `skillPaths`
 - `promptPaths`
-- `themePaths`
 
 Declared manifest paths are used first. When omitted, conventional folders are
 used if present:
 
 - `skills`
 - `prompts`
-- `themes`
 
-Skills become Pi `/skill:name` commands. Prompt templates and themes are
-surfaced through Pi's normal resource system.
+Skills become Pi `/skill:name` commands. Prompt templates are surfaced through
+Pi's normal resource system.
 
 ## Subagents
 

package/docs/recipe-cli.md

@@ -133,6 +133,9 @@ model:
 Objects such as `model` and `extensions` merge by key, while arrays such as
 `tools`, `skills`, and `subagents` replace the inherited array.
 
+Use `system_instructions.content: ""` when an agent intentionally adds no
+instructions beyond `SYSTEM.md` but still needs to declare the field explicitly.
+
 `SYSTEM.md` is optional. When present, Pi uses it as the recipe-level system
 prompt before applying the selected agent's `system_instructions`.
 
@@ -183,7 +186,6 @@ The `pi` block declares recipe-owned resources:
 - `extensions`: TypeScript extension globs
 - `skills`: skill paths or globs
 - `prompts`: prompt paths or globs
-- `themes`: theme paths or globs
 
 Normal package-manager fields such as `dependencies`, `optionalDependencies`,
 `peerDependencies`, `devDependencies`, `packageManager`, and lockfile metadata
@@ -201,8 +203,7 @@ boundaries:
     "agents": ["agents/*.yaml"],
     "extensions": ["extensions/*.ts", "extensions/*/index.ts"],
     "skills": ["skills/**/SKILL.md"],
-    "prompts": ["prompts"],
-    "themes": ["themes/*.json"]
+    "prompts": ["prompts"]
   }
 }
 ```
@@ -212,7 +213,6 @@ When entries are omitted, conventional folders are used if present:
 - `agents`
 - `skills`
 - `prompts`
-- `themes`
 
 `extensions` are only loaded when declared.
 
@@ -448,6 +448,8 @@ recipes publish ./my-recipe --github owner/my-recipe --visibility public
 `recipes publish` runs the same development validation as `doctor`, updates
 `package.json#name` to `@owner/my-recipe`, commits local changes, creates the
 GitHub repository when needed, pushes `main`, and re-registers the local recipe.
+When `--visibility public` is used, it also submits the public package metadata
+to the recipe catalog so the marketplace can add or refresh the listing.
 
 For a standalone public recipe:
 
@@ -506,6 +508,40 @@ recipes install github:owner/repo/recipes/code-review
 recipes install github:owner/repo/recipes/research#v1.0.0
 ```
 
+## Telemetry
+
+When you install a recipe from a remote source (`github:` or a Git URL),
+`recipes install` sends a single anonymous ping to the public recipe directory
+at [pi.recipes](https://pi.recipes) so it can rank recipes by install count.
+
+The ping contains only the recipe's canonical id, name, and version:
+
+```json
+{ "event": "install", "id": "github:owner/repo", "name": "my-recipe", "version": "1.0.0" }
+```
+
+No paths, machine identifiers, or other personal data are sent. Local recipe
+registration (`recipes install ./my-recipe`) is never reported. The ping is
+best-effort and never blocks or fails an install.
+
+When you publish with `--visibility public`, `recipes publish` sends the
+recipe's public GitHub source, package name, version, description, install
+command, homepage, and resource counts so it can appear in the catalog.
+
+Opt out by setting either environment variable to a truthy value:
+
+```bash
+DO_NOT_TRACK=1 recipes install github:owner/repo
+PI_RECIPES_NO_TELEMETRY=1 recipes install github:owner/repo
+```
+
+Point install pings or catalog submissions at different collectors with:
+
+```bash
+PI_RECIPES_TELEMETRY_ENDPOINT=https://example.com/api/installs recipes install github:owner/repo
+PI_RECIPES_CATALOG_ENDPOINT=https://example.com/api/catalog/recipes recipes publish . --github owner/my-recipe --visibility public
+```
+
 ## Troubleshooting
 
 If a private GitHub recipe fails to install with `github:owner/repo`, use SSH or

package/docs/recipe-flow.md

@@ -1,7 +1,7 @@
 # Pi Recipes: Install, Customize, Publish
 
 A recipe is a shareable Pi workflow package: it can add agents, instructions,
-skills, prompts, themes, and optional runtime extensions.
+skills, prompts, and optional runtime extensions.
 
 Use `recipes` to install recipes, make local edits, validate them, and
 publish your own.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/pi-recipes",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Local session tooling for package-based workflows.",
   "license": "UNLICENSED",
   "type": "module",
@@ -24,6 +24,8 @@
     "dist/recipe-publish.js",
     "dist/recipe-store.d.ts",
     "dist/recipe-store.js",
+    "dist/recipe-telemetry.d.ts",
+    "dist/recipe-telemetry.js",
     "docs",
     "README.md",
     "package.json"