@zenera/neo 1.1.0 → 1.1.3

package/README.md

@@ -153,7 +153,6 @@ of surfacing three turns into a run as a confused model.
 
 ## Documentation
 
-[DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/DESIGN.md) ·
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md) ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 · and

package/dist/models/factory.d.ts

@@ -46,7 +46,8 @@ export interface ProviderSpec extends Credentials {
     /**
      * vertex only: GCP project id. Falls back to `GOOGLE_CLOUD_PROJECT`, then
      * to the `project_id` inside the service-account key file named by
-     * `GOOGLE_APPLICATION_CREDENTIALS`.
+     * `GOOGLE_APPLICATION_CREDENTIALS`. Ignored when an `apiKey` is given —
+     * express mode addresses no project.
      */
     project?: string;
     /** vertex only: a region, or `global` (env: `GOOGLE_CLOUD_LOCATION`, default `global`) */

package/dist/models/factory.js

@@ -429,6 +429,12 @@ function buildOpenRouter(kind, apiKey, baseURL, headers, opts) {
  * application-default login` — and refreshes them itself. That is why `vertex`
  * is `keyOptional`, and why it needs none of the bearer-token machinery the
  * OpenAI protocol uses for the same job.
+ *
+ * A key and a project are alternatives, not a pair. An express-mode key
+ * authenticates against `aiplatform.googleapis.com` with no project in the
+ * path; naming a project as well makes the SDK build a project-scoped url and
+ * then authenticate it with the key header — a combination the service refuses,
+ * and one nothing in the resulting 403 attributes to having set both.
  */
 function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
     const { GoogleGenAI } = sdk('@google/genai', kind);
@@ -436,16 +442,18 @@ function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
     if (kind !== 'vertex') {
         return new GoogleGenAI({ apiKey, httpOptions });
     }
+    if (apiKey) {
+        return new GoogleGenAI({ vertexai: true, apiKey, httpOptions });
+    }
     const project = expand(opts.project, `${where}: project`) ??
         fromEnv('GOOGLE_CLOUD_PROJECT') ??
         projectFromKeyFile();
-    if (!project && !apiKey) {
+    if (!project) {
         throw new Error(`${where}: vertex needs \`project\`, or GOOGLE_CLOUD_PROJECT ` +
             `(or \`apiKey\` for express mode)`);
     }
     return new GoogleGenAI({
         vertexai: true,
-        apiKey,
         project,
         location: expand(opts.location, `${where}: location`) ??
             fromEnv('GOOGLE_CLOUD_LOCATION') ??

package/dist/project/config.d.ts

@@ -112,8 +112,24 @@ declare const embeddingSpec: z.ZodObject<{
     baseURL: z.ZodOptional<z.ZodString>;
     baseURLEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A Dockerfile to build instead of an image to pull, for the ordinary case the
+ * `image:` key cannot serve: a project that needs two runtimes, or a pinned
+ * toolchain, and would otherwise have its agents reinstall it on every run.
+ *
+ * Building is a host concern, so nothing in this library does it — the front
+ * end resolves this to an image reference before a container is ever named.
+ */
+declare const build: z.ZodObject<{
+    dockerfile: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 declare const sandbox: z.ZodObject<{
     image: z.ZodOptional<z.ZodString>;
+    build: z.ZodOptional<z.ZodObject<{
+        dockerfile: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     cpus: z.ZodOptional<z.ZodNumber>;
     memory: z.ZodOptional<z.ZodInt>;
     network: z.ZodOptional<z.ZodEnum<{
@@ -126,6 +142,7 @@ declare const sandbox: z.ZodObject<{
     user: z.ZodOptional<z.ZodString>;
     persist: z.ZodOptional<z.ZodBoolean>;
     env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    keys: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const projectSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -230,8 +247,13 @@ export declare const projectSchema: z.ZodObject<{
     }, z.core.$strict>]>>>;
     embedding: z.ZodOptional<z.ZodString>;
     skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    assets: z.ZodOptional<z.ZodString>;
     sandbox: z.ZodOptional<z.ZodObject<{
         image: z.ZodOptional<z.ZodString>;
+        build: z.ZodOptional<z.ZodObject<{
+            dockerfile: z.ZodString;
+            context: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         cpus: z.ZodOptional<z.ZodNumber>;
         memory: z.ZodOptional<z.ZodInt>;
         network: z.ZodOptional<z.ZodEnum<{
@@ -244,6 +266,7 @@ export declare const projectSchema: z.ZodObject<{
         user: z.ZodOptional<z.ZodString>;
         persist: z.ZodOptional<z.ZodBoolean>;
         env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        keys: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     agents: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -269,6 +292,10 @@ export declare const projectSchema: z.ZodObject<{
         }, z.core.$strict>]>>;
         sandbox: z.ZodOptional<z.ZodObject<{
             image: z.ZodOptional<z.ZodString>;
+            build: z.ZodOptional<z.ZodObject<{
+                dockerfile: z.ZodString;
+                context: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             cpus: z.ZodOptional<z.ZodNumber>;
             memory: z.ZodOptional<z.ZodInt>;
             network: z.ZodOptional<z.ZodEnum<{
@@ -281,6 +308,7 @@ export declare const projectSchema: z.ZodObject<{
             user: z.ZodOptional<z.ZodString>;
             persist: z.ZodOptional<z.ZodBoolean>;
             env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            keys: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         default: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
@@ -291,6 +319,7 @@ export type ProviderConfig = z.infer<typeof provider>;
 export type ModelConfig = z.infer<typeof modelSpec>;
 export type EmbeddingConfig = z.infer<typeof embeddingSpec>;
 export type SandboxConfig = z.infer<typeof sandbox>;
+export type SandboxBuildConfig = z.infer<typeof build>;
 /**
  * Re-renders a zod failure as `agents.yaml: agents[1].skills.discovery — …`.
  *

package/dist/project/config.js

@@ -165,15 +165,35 @@ const forkBinding = z
  *
  * `env` names host variables to forward, and only names: values never appear
  * in the config, so a repository never carries one. Names that read like a
- * credential are refused outright. The CLI materialises the keyring into its
- * own environment before loading a project, so an unguarded passthrough would
- * hand every model key to whatever the agent decided to run.
+ * credential are refused outright — not because credentials never belong in
+ * the sandbox, but because `env` is the wrong door for them. Model keys go
+ * through `keys`, which forwards a known set by name and can be turned off in
+ * one place; a hand-written `env: [OPENAI_API_KEY]` would be a second, silent
+ * way in that no single switch could close.
  */
 const SECRETISH = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)/i;
+/**
+ * A Dockerfile to build instead of an image to pull, for the ordinary case the
+ * `image:` key cannot serve: a project that needs two runtimes, or a pinned
+ * toolchain, and would otherwise have its agents reinstall it on every run.
+ *
+ * Building is a host concern, so nothing in this library does it — the front
+ * end resolves this to an image reference before a container is ever named.
+ */
+const build = z
+    .object({
+    /** path to the Dockerfile, relative to the project root */
+    dockerfile: z.string().min(1),
+    /** what the build may COPY from; the Dockerfile's own directory by default */
+    context: z.string().min(1).optional(),
+})
+    .strict();
 const sandbox = z
     .object({
     /** the base image, e.g. `docker.io/library/python:3.13-slim` */
     image: z.string().min(1).optional(),
+    /** a Dockerfile to build, instead of an image to pull */
+    build: build.optional(),
     /** fractional cores the container may use */
     cpus: z.number().positive().optional(),
     /** MiB the container may use */
@@ -189,19 +209,40 @@ const sandbox = z
     persist: z.boolean().optional(),
     /** host variables to forward, by name */
     env: z.array(z.string().min(1)).optional(),
+    /**
+     * Whether the model credentials reach the sandbox. On by default,
+     * because the scaffolded image installs `zen` itself and an agent that
+     * cannot run `zen models` inside its own sandbox is a surprise.
+     *
+     * Turning it off is the honest answer for a project whose agents write
+     * code they then execute: the container runs whatever the model wrote,
+     * so a forwarded key is a key that code can read and, on a `bridge`
+     * network, send somewhere.
+     */
+    keys: z.boolean().optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
-    for (const [i, name] of (value.env ?? []).entries()) {
-        if (SECRETISH.test(name)) {
-            ctx.addIssue({
-                code: 'custom',
-                path: ['env', i],
-                message: `refusing to forward ${name} into the sandbox — it reads like a ` +
-                    'credential, and the sandbox runs whatever the model writes',
-            });
-        }
+    if (value.image !== undefined && value.build !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['build'],
+            message: 'image and build cannot both be set — a Dockerfile names its own base ' +
+                'in its FROM line, so one of the two would be silently ignored',
+        });
     }
+    // Disable key blacklisting for now.
+    // for (const [i, name] of (value.env ?? []).entries()) {
+    //     if (SECRETISH.test(name)) {
+    //         ctx.addIssue({
+    //             code: 'custom',
+    //             path: ['env', i],
+    //             message:
+    //                 `refusing to forward ${name} into the sandbox — it reads like a ` +
+    //                 'credential, and the sandbox runs whatever the model writes',
+    //         });
+    //     }
+    // }
 });
 const agent = z
     .object({
@@ -255,6 +296,12 @@ export const projectSchema = z
     embedding: modelRef.optional(),
     /** one directory, or several merged into one catalog */
     skills: z.union([z.string().min(1), z.array(z.string().min(1))]).optional(),
+    /**
+     * Reference material every agent can read and none can write, mounted
+     * at /assets. One directory, project-wide: an agent that may only see
+     * some of it is a different project, not a different key.
+     */
+    assets: z.string().min(1).optional(),
     /** the container `run_command` and friends execute in */
     sandbox: sandbox.optional(),
     agents: z.array(agent).min(1),

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
-export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxConfig, } from './config.ts';
-export { AgentProject, loadProject, projectRegistry, readProjectConfig, type ProjectOptions, type ProjectSource, } from './load.ts';
+export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
+export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
 export { projectDir, projectFile, projectPath, projectRoot } from './refs.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/project/index.js

@@ -1,4 +1,4 @@
 export { parseConfig, projectSchema, } from "./config.js";
-export { AgentProject, loadProject, projectRegistry, readProjectConfig, } from "./load.js";
+export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, } from "./load.js";
 export { projectDir, projectFile, projectPath, projectRoot } from "./refs.js";
 //# sourceMappingURL=index.js.map

package/dist/project/load.d.ts

@@ -5,6 +5,7 @@ import type { MemoryStore } from '../memory.ts';
 import { ModelRegistry, type EmbeddingRef, type ModelRef, type ProviderSpec } from '../models/factory.ts';
 import type { PayloadStore } from '../payload.ts';
 import { AgentRunner, type RunOptions, type RunnerOptions } from '../runner.ts';
+import { type SkillDir } from '../skill-providers/file.ts';
 import type { SkillProvider } from '../skills.ts';
 import { type AnyTool, type Input } from '../types.ts';
 import { type ProjectConfig } from './config.ts';
@@ -16,6 +17,7 @@ import { type ProjectConfig } from './config.ts';
  * agents.yaml                   who exists, what they may reach for
  * agents/prompts/<role>.md      one agent's own instructions
  * agents/skills/<name>/SKILL.md
+ * assets/                       reference material, mounted read-only at /assets
  * ```
  *
  * The loader turns that into the objects an author would otherwise write by
@@ -56,6 +58,16 @@ export interface ProjectOptions<TCtx = unknown> {
     payloads?: PayloadStore;
     /** extra providers merged with the ones the project declares */
     skills?: SkillProvider[];
+    /**
+     * Where the host has mounted the skill catalog for the agent to reach —
+     * `/skills` from the CLI, which bind-mounts it into the container.
+     *
+     * Set it and a loaded skill carries the path of its own folder, so one that
+     * ships a script can say where the script is. Left unset, a skill is text
+     * and nothing claims otherwise: a promise of a directory that is not there
+     * is worse than no directory.
+     */
+    skillsAt?: string;
 }
 /** A project's declaration, before anything is assembled from it. */
 export interface ProjectSource {
@@ -85,6 +97,7 @@ interface ProjectParts<TCtx> {
     entry: string;
     registry: AgentRegistry<TCtx>;
     skillProviders: SkillProvider[];
+    assets: string | undefined;
     models: ModelRegistry;
     embedders: (ref: string | undefined, where: string) => Embedder | undefined;
     options: ProjectOptions<TCtx>;
@@ -112,6 +125,8 @@ export declare class AgentProject<TCtx = unknown> {
     readonly entry: string;
     readonly registry: AgentRegistry<TCtx>;
     readonly skillProviders: readonly SkillProvider[];
+    /** reference material to mount read-only, if the project has any */
+    readonly assets: string | undefined;
     /** the providers this project declared, and the clients behind them */
     readonly models: ModelRegistry;
     constructor(parts: ProjectParts<TCtx>);
@@ -138,5 +153,30 @@ export declare class AgentProject<TCtx = unknown> {
  * for, and only pay for it if an agent actually reaches for it.
  */
 export declare function projectRegistry<TCtx>(config: ProjectConfig, opts?: ProjectOptions<TCtx>): ModelRegistry;
+/**
+ * Where each skill directory appears in the agent's namespace.
+ *
+ * One catalog is the whole of `/skills`, which is what a project normally has.
+ * Several cannot all be it, so each takes its own last segment underneath — and
+ * two directories ending in the same name would mean one hid the other, which
+ * is a load error rather than a catalog that silently went missing.
+ */
+export declare function skillMounts(dirs: readonly string[], at: string): SkillDir[];
+/**
+ * The directories the skill catalog is built from, resolved. `skills:` if it is
+ * there, otherwise the conventional folder if it exists, otherwise none — a
+ * project without skills is a project, not an error.
+ */
+export declare function skillDirs(root: string, config: ProjectConfig): string[];
+/**
+ * The project's reference material, resolved, or undefined if it has none.
+ *
+ * Convention first — `assets/` next to `agents.yaml` is enough, and a project
+ * that only wants somewhere to put a handbook writes no config at all. The key
+ * exists for the project that keeps its material elsewhere in the tree; a key
+ * naming a directory that is not there is a mistake in the file and fails at
+ * load, where the conventional folder merely being absent does not.
+ */
+export declare function assetsDir(root: string, config: ProjectConfig): string | undefined;
 export {};
 //# sourceMappingURL=load.d.ts.map

package/dist/project/load.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
 import { ModelRegistry, } from "../models/factory.js";
@@ -11,6 +11,8 @@ import { parseConfig } from "./config.js";
 import { projectDir, projectFile, projectRoot } from "./refs.js";
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
+/** Reference material, by convention, when `assets:` says nothing. */
+const ASSETS_DIR = 'assets';
 const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents/agents.yml'];
 // Deliberately not `AGENTS.md`: every coding assistant now reads that name out
 // of an open folder, and `zen open` opens exactly this directory. The house
@@ -42,6 +44,9 @@ export async function loadProject(dir, opts = {}) {
     const providers = [...skillProviders(root, config, opts), ...(opts.skills ?? [])];
     const catalogs = await indexOf(providers);
     const models = projectRegistry(config, opts);
+    // Resolved here rather than where it is mounted, so an `assets:` naming a
+    // directory that is not there fails at load like every other bad path.
+    const assets = assetsDir(root, config);
     const registry = new AgentRegistry();
     const resolve = modelResolver(config, opts, models);
     for (const spec of config.agents) {
@@ -68,6 +73,7 @@ export async function loadProject(dir, opts = {}) {
         entry: entrypoint(config),
         registry,
         skillProviders: providers,
+        assets,
         models,
         embedders,
         options: opts,
@@ -95,6 +101,8 @@ export class AgentProject {
     entry;
     registry;
     skillProviders;
+    /** reference material to mount read-only, if the project has any */
+    assets;
     /** the providers this project declared, and the clients behind them */
     models;
     #embedders;
@@ -107,6 +115,7 @@ export class AgentProject {
         this.entry = parts.entry;
         this.registry = parts.registry;
         this.skillProviders = parts.skillProviders;
+        this.assets = parts.assets;
         this.models = parts.models;
         this.#embedders = parts.embedders;
         this.#options = parts.options;
@@ -307,13 +316,7 @@ function forkFor(spec) {
     return spec.fork === true ? {} : spec.fork;
 }
 function skillProviders(root, config, opts) {
-    const declared = config.skills
-        ? Array.isArray(config.skills)
-            ? config.skills
-            : [config.skills]
-        : existsSync(join(root, SKILLS_DIR))
-            ? [SKILLS_DIR]
-            : [];
+    const declared = skillDirs(root, config);
     if (!declared.length) {
         return [];
     }
@@ -323,11 +326,65 @@ function skillProviders(root, config, opts) {
     return [
         new FileSkillProvider({
             id: 'project',
-            dir: declared.map((d, i) => projectDir(root, d, `skills[${i}]`)),
+            dir: opts.skillsAt ? skillMounts(declared, opts.skillsAt) : declared,
             tools: opts.tools,
         }),
     ];
 }
+/**
+ * Where each skill directory appears in the agent's namespace.
+ *
+ * One catalog is the whole of `/skills`, which is what a project normally has.
+ * Several cannot all be it, so each takes its own last segment underneath — and
+ * two directories ending in the same name would mean one hid the other, which
+ * is a load error rather than a catalog that silently went missing.
+ */
+export function skillMounts(dirs, at) {
+    if (dirs.length === 1) {
+        return [{ path: dirs[0], at }];
+    }
+    const taken = new Map();
+    return dirs.map((dir) => {
+        const name = basename(dir);
+        const clash = taken.get(name);
+        if (clash) {
+            throw new Error(`skills: ${dir} and ${clash} would both be mounted at ${at}/${name}`);
+        }
+        taken.set(name, dir);
+        return { path: dir, at: `${at}/${name}` };
+    });
+}
+/**
+ * The directories the skill catalog is built from, resolved. `skills:` if it is
+ * there, otherwise the conventional folder if it exists, otherwise none — a
+ * project without skills is a project, not an error.
+ */
+export function skillDirs(root, config) {
+    const declared = config.skills
+        ? Array.isArray(config.skills)
+            ? config.skills
+            : [config.skills]
+        : existsSync(join(root, SKILLS_DIR))
+            ? [SKILLS_DIR]
+            : [];
+    return declared.map((d, i) => projectDir(root, d, `skills[${i}]`));
+}
+/**
+ * The project's reference material, resolved, or undefined if it has none.
+ *
+ * Convention first — `assets/` next to `agents.yaml` is enough, and a project
+ * that only wants somewhere to put a handbook writes no config at all. The key
+ * exists for the project that keeps its material elsewhere in the tree; a key
+ * naming a directory that is not there is a mistake in the file and fails at
+ * load, where the conventional folder merely being absent does not.
+ */
+export function assetsDir(root, config) {
+    if (config.assets) {
+        return projectDir(root, config.assets, 'assets');
+    }
+    const at = join(root, ASSETS_DIR);
+    return existsSync(at) && statSync(at).isDirectory() ? at : undefined;
+}
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------

package/dist/skill-providers/file.d.ts

@@ -1,8 +1,18 @@
 import type { Skill, SkillProvider, SkillSummary } from '../skills.ts';
 import { type AnyTool } from '../types.ts';
+/**
+ * A directory of skills, and the name the *agent* reaches it by — which is not
+ * the host path when the folder is bind-mounted into a container. Give the
+ * plain string and a skill is text; give the pair and a skill that ships a
+ * script can say where the script is.
+ */
+export interface SkillDir {
+    path: string;
+    at: string;
+}
 export interface FileSkillProviderOptions {
-    /** one or more root directories holding `<name>.md` files and/or `<name>/SKILL.md` folders */
-    dir: string | string[];
+    /** one or more root directories holding `<name>/SKILL.md` folders, or bare `<name>.md` files */
+    dir: string | SkillDir | (string | SkillDir)[];
     /** logical provider id agents bind to; defaults to `file` */
     id?: string;
     /**
@@ -14,13 +24,18 @@ export interface FileSkillProviderOptions {
     tools?: AnyTool<any>[];
 }
 /**
- * Reads skills from disk. Two layouts, both discovered in one scan:
+ * Reads skills from disk. A skill is a directory holding `SKILL.md`, and the
+ * directory is what lets it ship a rate table or a script beside its text:
  *
  * ```
- * <dir>/budget_travel.md          flat: frontmatter + body
- * <dir>/budget_travel/SKILL.md    folder: sibling files become `resources`
+ * <dir>/budget_travel/SKILL.md    the instructions
+ * <dir>/budget_travel/cities.md   whatever they refer to
  * ```
  *
+ * A bare `<dir>/budget_travel.md` is indexed too, for a host with nothing but
+ * prose to offer. `zen check` refuses it in a project, since a skill with no
+ * directory of its own can never grow one.
+ *
  * Frontmatter is a small subset of YAML — `key: value`, plus `[a, b]` lists
  * for `tags` and `tools`. `name` defaults to the file or folder name and
  * `description` to the first line of the body, so the minimum viable skill is

package/dist/skill-providers/file.js

@@ -1,18 +1,23 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { selectTools } from "../types.js";
 // ---------------------------------------------------------------------------
 // Filesystem-backed skill provider
 // ---------------------------------------------------------------------------
 const SKILL_FILE = 'SKILL.md';
 /**
- * Reads skills from disk. Two layouts, both discovered in one scan:
+ * Reads skills from disk. A skill is a directory holding `SKILL.md`, and the
+ * directory is what lets it ship a rate table or a script beside its text:
  *
  * ```
- * <dir>/budget_travel.md          flat: frontmatter + body
- * <dir>/budget_travel/SKILL.md    folder: sibling files become `resources`
+ * <dir>/budget_travel/SKILL.md    the instructions
+ * <dir>/budget_travel/cities.md   whatever they refer to
  * ```
  *
+ * A bare `<dir>/budget_travel.md` is indexed too, for a host with nothing but
+ * prose to offer. `zen check` refuses it in a project, since a skill with no
+ * directory of its own can never grow one.
+ *
  * Frontmatter is a small subset of YAML — `key: value`, plus `[a, b]` lists
  * for `tags` and `tools`. `name` defaults to the file or folder name and
  * `description` to the first line of the body, so the minimum viable skill is
@@ -26,7 +31,9 @@ export class FileSkillProvider {
     constructor(opts) {
         const o = typeof opts === 'string' ? { dir: opts } : opts;
         const raw = Array.isArray(o.dir) ? o.dir : [o.dir];
-        this.#dirs = raw.map((d) => resolve(d));
+        this.#dirs = raw.map((d) => typeof d === 'string'
+            ? { path: resolve(d), at: '' }
+            : { path: resolve(d.path), at: d.at });
         this.id = o.id ?? 'file';
         for (const t of o.tools ?? []) {
             this.#tools.set(t.name, t);
@@ -34,11 +41,11 @@ export class FileSkillProvider {
     }
     /** The first configured directory (kept for backwards compatibility). */
     get dir() {
-        return this.#dirs[0];
+        return this.#dirs[0].path;
     }
     /** All configured directories. */
     get dirs() {
-        return [...this.#dirs];
+        return this.#dirs.map((d) => d.path);
     }
     /** Drops the cached scan; call after editing skills on disk. */
     refresh() {
@@ -77,7 +84,7 @@ export class FileSkillProvider {
             content: entry.content,
             file: entry.file,
             ...(tools.length ? { tools } : {}),
-            ...(entry.folder ? { resources: await readResources(entry.folder) } : {}),
+            ...(entry.at ? { path: entry.at } : {}),
         };
     }
     tool(name) {
@@ -93,7 +100,7 @@ export class FileSkillProvider {
         for (const dir of this.#dirs) {
             let items;
             try {
-                items = await readdir(dir, { withFileTypes: true });
+                items = await readdir(dir.path, { withFileTypes: true });
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
@@ -102,8 +109,8 @@ export class FileSkillProvider {
                 throw err;
             }
             for (const item of items) {
-                const folder = item.isDirectory() ? join(dir, item.name) : undefined;
-                const file = folder ? join(folder, SKILL_FILE) : join(dir, item.name);
+                const folder = item.isDirectory() ? join(dir.path, item.name) : undefined;
+                const file = folder ? join(folder, SKILL_FILE) : join(dir.path, item.name);
                 if (!folder && !(item.isFile() && item.name.endsWith('.md'))) {
                     continue;
                 }
@@ -112,20 +119,24 @@ export class FileSkillProvider {
                     continue;
                 }
                 const base = folder ? item.name : item.name.slice(0, -'.md'.length);
-                const entry = parse(raw, base, file, folder);
+                // Only a folder skill has files of its own to point at, and
+                // only when the host said where the directory can be reached.
+                const at = folder && dir.at ? `${dir.at}/${basename(folder)}` : undefined;
+                const entry = parse(raw, base, file, folder, at);
                 index.set(entry.summary.name, entry);
             }
         }
         return index;
     }
 }
-function parse(raw, base, file, folder) {
+function parse(raw, base, file, folder, at) {
     const { data, body } = frontmatter(raw);
     const tags = toList(data.tags);
     const tools = toList(data.tools);
     return {
         file,
         folder,
+        ...(at ? { at } : {}),
         content: body,
         summary: {
             name: data.name || base,
@@ -136,20 +147,6 @@ function parse(raw, base, file, folder) {
         },
     };
 }
-/** Sibling files of a `SKILL.md`, top level only, keyed by filename. */
-async function readResources(folder) {
-    const out = {};
-    for (const item of await readdir(folder, { withFileTypes: true })) {
-        if (!item.isFile() || item.name === SKILL_FILE) {
-            continue;
-        }
-        const value = await readOptional(join(folder, item.name));
-        if (value !== undefined) {
-            out[item.name] = value;
-        }
-    }
-    return out;
-}
 async function readOptional(path) {
     try {
         return await readFile(path, 'utf8');

package/dist/skills.d.ts

@@ -23,7 +23,14 @@ export interface Skill extends SkillSummary {
     content: string;
     /** tools unlocked while the skill is active; the context type is the host agent's */
     tools?: AnyTool<any>[];
-    resources?: Record<string, string>;
+    /**
+     * Where the skill's own files are, *under a name the agent can use* — not a
+     * host path. A skill that ships a script is instructions plus that script,
+     * and its text says "run scripts/fill.py" without saying where `scripts/`
+     * is; this is the answer, and it is only set when the host has actually put
+     * the folder somewhere the agent can reach.
+     */
+    path?: string;
     /** absolute path of the source file, if known (set by file-backed providers) */
     file?: string;
 }