melchizedek-agents 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.8.0 — 2026-10-18
+
+A minor release that gives a repository a manifest (ADR 0138). A
+`melchizedek.json` at the root names the agents folder, the exact engine
+version the project is written for, and how each syndicate ships; the
+bins find it on their own, `melchizedek-doctor` checks the pin, and the
+desktop app opens a repository through it. Nothing changes for a
+deployment that sets `MELCHIZEDEK_AGENTS_DIR`.
+
+### Added
+
+- **The project manifest, `melchizedek.json` (ADR 0138).** A JSON file at
+  a repository's root naming its agents folder (`agents`), the engine
+  version it is written for (`engine`, an exact pin), an `ignore` list,
+  a `tests` folder, the env variable *names* it needs, and per-file
+  shipping records (`syndicates.<file>.deliverable`,
+  `publish: { kind: "registry", id }`). New subpath
+  `melchizedek-agents/project` and barrel exports: `findProject`,
+  `loadProject`, `parseProjectManifest`, `resolveAgentsDir`,
+  `listProjectSyndicates`, `checkProject`, `projectManifestSchema`.
+- **The agents directory reads the manifest.** Every loader and bin
+  resolves it as: explicit option, `MELCHIZEDEK_AGENTS_DIR`, the nearest
+  manifest's `agents` (not above the repository root), then
+  `<cwd>/config/agents`. A deployment that sets the variable is
+  unchanged.
+- **`melchizedek-doctor` reports the project**: the engine pin against
+  the running engine, a missing agents or tests folder, `ignore`
+  patterns that match nothing, unset env names, and `syndicates` keys
+  with no file. A pin mismatch or a missing folder fails `--check`.
+
 ## 1.7.0 — 2026-10-17
 
 A minor release that lets a syndicate hold code (ADR 0137). A `script:`

package/DOCUMENTATION.md

@@ -1610,22 +1610,27 @@ subclass), and register it behind a model-id prefix.
 subagent. `scripts/demo_mcp_server.ts` is a complete server to copy —
 tool definitions, SSE wiring, and persistent state in ~250 lines.
 
-**Teach your coding agent the framework**: `skills/` holds six Agent
+**Teach your coding agent the framework**: `skills/` holds eleven Agent
 Skills (the open SKILL.md standard — a directory per skill, `name` and
 `description` frontmatter) that give Claude Code, Codex, Cursor,
 OpenCode or Gemini CLI the catalog of syndicates and the procedures in
 this document: `melchizedek` (find and run, delegate a task),
 `melchizedek-author`, `melchizedek-serve`, `melchizedek-memory`,
-`melchizedek-models`, `melchizedek-scribe`. `npx melchizedek-skills
+`melchizedek-models`, `melchizedek-scribe`, and five onboarding skills
+that route a person by the credentials they have — `melchizedek-onboard`
+(the triage) and `melchizedek-onboard-local`, `-keys`, `-cloud` and
+`-serve` (the authentication levels each owns). `npx melchizedek-skills
 install` copies them into `.claude/skills/` and `.agents/skills/` of the
 current project (`--for claude,codex,cursor,opencode,gemini,agents,all`,
 `--global`, `--dir <path>`, `--only <names>`, `--force`, `--dry-run`;
 `npm run skills:install` in a clone). The installer (`lib/skills.ts`)
 copies only from the package's own `skills/` directory, follows no
-symlinks, and never overwrites a differing file without `--force`. Each
-SKILL.md body was written by the Scribe syndicate
-(`config/agents/examples/scribe.yaml`) from a brief of facts and reviewed
-by a person; `skills/README.md` records the procedure.
+symlinks, and never overwrites a differing file without `--force`. The
+onboarding skills are short procedures written by hand that print their
+facts from `melchizedek-setup --level <id>`; every other SKILL.md body was
+written by the Scribe syndicate (`config/agents/examples/scribe.yaml`)
+from a brief of facts and reviewed by a person; `skills/README.md`
+records the procedure.
 
 ## 8. Security notes
 

package/dist/lib/doctor.d.ts

@@ -27,6 +27,7 @@ import type { Platform } from './models/endpoints.ts';
 import type { CapabilityGap, CapabilityReport } from './models/capabilities.ts';
 import type { ProviderId } from './models/providerMap.ts';
 import type { RuntimeName, RuntimeSource } from './runtime/runtimeFlag.ts';
+import { type ProjectCheck } from './project.ts';
 /**
  * What a file costs to run: `keyless` (all Ollama), a single provider's id
  * when every agent shares one (`gemini`, `anthropic`, `openai`, `xai` — one
@@ -169,7 +170,16 @@ export interface DoctorResult {
     serving?: DoctorServing;
     /** A stored Sign in with ChatGPT credential (ADR 0126), when one is present or its variables are set. */
     chatgpt?: DoctorChatGpt;
+    /** The project manifest (ADR 0138) found from the working directory, when there is one. */
+    project?: DoctorProject;
 }
+/** A `melchizedek.json` at or above the working directory: its checks, or why it does not load. */
+export type DoctorProject = ProjectCheck | {
+    root: string;
+    error: string;
+    problems: string[];
+    warnings: string[];
+};
 /**
  * A Sign in with ChatGPT credential (ADR 0126): where it is, whether it is
  * signed in and carries OpenAI ids here, and what stops it. Never a token.

package/dist/lib/doctor.js

@@ -42,6 +42,7 @@ import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
 import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
 import { syndicateCredentialUses } from './tools/credentialUses.js';
 import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
+import { checkProject, findProject, isIgnored, ProjectManifestError, resolveAgentsDir } from './project.js';
 /** The `gateway.id` the doctor reports when `MODEL_GATEWAY` names no known gateway; the value itself is never kept. */
 const UNRECOGNISED_GATEWAY = 'unrecognised';
 function resolvable(module) {
@@ -457,10 +458,11 @@ export function flagMemoryNamespaces(syndicates) {
     }
 }
 export function runDoctor(options = {}) {
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
-    const syndicates = listSyndicateFiles(agentsDir).map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
+    const agentsDir = resolveAgentsDir(options.agentsDir);
+    const { project, report: projectReport } = projectFromCwd();
+    // The manifest's ignore list applies when the doctor reads the project's own folder.
+    const listed = listSyndicateFiles(agentsDir).filter((f) => !project || agentsDir !== project.agentsDir || !isIgnored(project, path.relative(project.root, path.join(agentsDir, f))));
+    const syndicates = listed.map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
     // Which single variable unlocks what. A syndicate counts toward a
     // variable only when that variable is ALL it is missing.
     const byEnv = new Map();
@@ -541,8 +543,22 @@ export function runDoctor(options = {}) {
         providers: providerPaths(),
         ...(serving ? { serving } : {}),
         ...(chatgpt ? { chatgpt } : {}),
+        ...(projectReport ? { project: projectReport } : {}),
     };
 }
+/** The project at or above the working directory, checked; a broken manifest becomes a problem, not a throw. */
+function projectFromCwd() {
+    try {
+        const project = findProject();
+        return project ? { project, report: checkProject(project) } : {};
+    }
+    catch (e) {
+        if (!(e instanceof ProjectManifestError))
+            throw e;
+        const problem = `melchizedek.json: ${e.issues.join('; ')}`;
+        return { report: { root: path.dirname(e.file), error: problem, problems: [problem], warnings: [] } };
+    }
+}
 /**
  * The Sign in with ChatGPT line (ADR 0126), when a credential file is present
  * or one of its variables is set. `served`: a serving variable is set, so
@@ -613,6 +629,8 @@ export function checkProblems(result) {
         problems.push(`credentials: ${p}`);
     for (const p of result.chatgpt?.problems ?? [])
         problems.push(`chatgpt: ${p}`);
+    for (const p of result.project?.problems ?? [])
+        problems.push(`project: ${p}`);
     for (const s of result.syndicates) {
         for (const g of s.grants ?? [])
             for (const p of g.hostProblems ?? [])
@@ -635,6 +653,17 @@ export function renderDoctor(result, opts = {}) {
             : `${c.green}${text}${c.reset}`;
     lines.push(`${c.bold}melchizedek doctor${c.reset} ${c.dim}· ${result.agentsDir}${c.reset}`);
     lines.push('');
+    // The project manifest (ADR 0138): the engine pin, and what in it is stale.
+    if (result.project) {
+        const p = result.project;
+        const pin = 'engine' in p ? `${p.engine.matches ? c.green + '✓' : c.red + '✗'}${c.reset} engine ${p.engine.pinned}${p.engine.matches ? '' : `${c.red}, ${p.engine.running} running${c.reset}`} · ${p.syndicates.length} syndicate(s) ` : '';
+        lines.push(`project     ${pin}${c.dim}${p.root}${c.reset}`);
+        for (const x of p.problems)
+            if (!x.startsWith('engine:'))
+                lines.push(`            ${c.red}✗ ${x}${c.reset}`);
+        for (const x of p.warnings)
+            lines.push(`            ${c.yellow}! ${x}${c.reset}`);
+    }
     // The runtime a turn would run on, and where that came from (ADR 0107).
     if (result.runtime) {
         const rt = result.runtime;

package/dist/lib/index.d.ts

@@ -67,3 +67,4 @@ export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logP
 export { loadEnv } from './loadEnv.ts';
 export { setCredentialSource, credentialValue } from './models/credentialSource.ts';
 export type { CredentialSource } from './models/credentialSource.ts';
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, type Project, type ProjectManifest, type ProjectCheck, } from './project.ts';

package/dist/lib/index.js

@@ -55,3 +55,5 @@ describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayPr
 export { loadEnv } from './loadEnv.js';
 // Where credentials are read, by environment variable name (ADR 0133).
 export { setCredentialSource, credentialValue } from './models/credentialSource.js';
+// Project manifest, melchizedek.json (ADR 0138).
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, } from './project.js';

package/dist/lib/loadSyndicate.js

@@ -5,6 +5,7 @@ import { createClient } from '@supabase/supabase-js';
 import { hasSupabaseCredentials } from './persistence/supabaseProvider.js';
 import { validateSyndicateConfig } from './syndicateSchema.js';
 import { v1SpellingsOf } from './agentDialect.js';
+import { resolveAgentsDir } from './project.js';
 // ── Variable Injection (private) ──────────────────────────
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
@@ -290,10 +291,8 @@ export function readSyndicateFile(filename, options = {}) {
     // Security: confine reads to the agents root. `filename` can originate from
     // a network-controlled path segment (see a2a_server dynamic routes), so we
     // must reject any value that resolves outside that root (e.g. "../../.env").
-    // The root itself is trusted configuration: option → env → cwd default.
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
+    // The root itself is trusted configuration: option → env → project manifest → cwd default (lib/project.ts).
+    const agentsDir = resolveAgentsDir(options.agentsDir);
     let filePath = path.resolve(agentsDir, filename);
     if (filePath !== agentsDir && !filePath.startsWith(agentsDir + path.sep)) {
         throw new Error(`Invalid syndicate path: '${filename}' resolves outside the agents directory`);

package/dist/lib/project.d.ts

@@ -0,0 +1,116 @@
+/**
+ * lib/project.ts — the project manifest, `melchizedek.json` (ADR 0138).
+ *
+ * A project is a folder, usually a git repository, with a `melchizedek.json`
+ * at its root. The manifest records what the engine cannot infer from the
+ * files: which folder holds the syndicates, which engine version the project
+ * is written for, and how each file ships. It holds names, never values: an
+ * `env` entry is a variable name, and no field may carry a secret.
+ *
+ * `findProject()` walks up from a directory to the nearest manifest and stops
+ * at the repository root (the first directory holding `.git`) or the home
+ * directory, so a manifest outside the repository never steers it.
+ * `resolveAgentsDir()` is the one agents-directory chain every loader and bin
+ * uses: explicit option → MELCHIZEDEK_AGENTS_DIR → the manifest's `agents` →
+ * <cwd>/config/agents. A deployed server sets the variable, so the manifest
+ * only changes what a bare command run inside a project finds.
+ *
+ * Imports only node built-ins, zod and lib/paths.ts.
+ */
+import { z } from 'zod';
+export declare const PROJECT_MANIFEST = "melchizedek.json";
+export declare const MANIFEST_VERSION = 1;
+export declare const projectManifestSchema: z.ZodObject<{
+    manifest: z.ZodNumber;
+    engine: z.ZodString;
+    agents: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tests: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    syndicates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        deliverable: z.ZodOptional<z.ZodEnum<{
+            library: "library";
+            mcp: "mcp";
+            service: "service";
+        }>>;
+        publish: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"registry">;
+            id: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    registry: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"supabase">;
+        url_env: z.ZodOptional<z.ZodString>;
+        restart: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    production: z.ZodOptional<z.ZodObject<{
+        ledger: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"postgres">;
+            url_env: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        remote: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            mcp_env: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProjectManifest = z.infer<typeof projectManifestSchema>;
+export interface Project {
+    /** The folder holding `melchizedek.json`. */
+    root: string;
+    /** Absolute path of the manifest. */
+    file: string;
+    manifest: ProjectManifest;
+    /** `agents`, resolved under the root. */
+    agentsDir: string;
+    /** `tests`, resolved under the root (default `tests/agents`). */
+    testsDir: string;
+}
+/** Thrown for a manifest that does not parse or validate; names the file and fields, never a value. */
+export declare class ProjectManifestError extends Error {
+    readonly file: string;
+    readonly issues: string[];
+    constructor(file: string, issues: string[]);
+}
+/**
+ * The nearest folder at or above `from` holding a manifest, without crossing
+ * the repository root or the home directory. Undefined when there is none.
+ */
+export declare function findProjectRoot(from?: string): string | undefined;
+/** Parse and validate a manifest's text. Throws `ProjectManifestError`. */
+export declare function parseProjectManifest(text: string, file?: string): ProjectManifest;
+/** Load the project rooted at `root` (the folder holding the manifest). Throws `ProjectManifestError`. */
+export declare function loadProject(root: string): Project;
+/** The project at or above `from`, or undefined when there is none. Throws on a broken manifest. */
+export declare function findProject(from?: string): Project | undefined;
+/** Forget cached manifest lookups (tests, and an embedder that edits the manifest in-process). */
+export declare function clearProjectCache(): void;
+/**
+ * The agents directory: `explicit` → MELCHIZEDEK_AGENTS_DIR → the nearest
+ * manifest's `agents` → <cwd>/config/agents. Always absolute.
+ */
+export declare function resolveAgentsDir(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/** True when `relFromRoot` (a `/`-separated path relative to the project root) matches an `ignore` pattern. */
+export declare function isIgnored(project: Pick<Project, 'manifest'>, relFromRoot: string): boolean;
+/** The syndicate files directly in the agents folder, as names relative to it, minus `ignore`. */
+export declare function listProjectSyndicates(project: Project): string[];
+/** The installed engine's package version (no commit suffix). */
+export declare function enginePackageVersion(): string;
+export interface ProjectCheck {
+    root: string;
+    agentsDir: string;
+    /** The manifest's engine pin, and the engine running now. */
+    engine: {
+        pinned: string;
+        running: string;
+        matches: boolean;
+    };
+    syndicates: string[];
+    /** Stop `melchizedek-doctor --check`. */
+    problems: string[];
+    /** Shown, never fatal. */
+    warnings: string[];
+}
+/** What is wrong with a project: engine pin, missing folders, stale ignores, unset env names. Never reads a value. */
+export declare function checkProject(project: Project, running?: string, env?: NodeJS.ProcessEnv): ProjectCheck;

package/dist/lib/project.js

@@ -0,0 +1,274 @@
+/**
+ * lib/project.ts — the project manifest, `melchizedek.json` (ADR 0138).
+ *
+ * A project is a folder, usually a git repository, with a `melchizedek.json`
+ * at its root. The manifest records what the engine cannot infer from the
+ * files: which folder holds the syndicates, which engine version the project
+ * is written for, and how each file ships. It holds names, never values: an
+ * `env` entry is a variable name, and no field may carry a secret.
+ *
+ * `findProject()` walks up from a directory to the nearest manifest and stops
+ * at the repository root (the first directory holding `.git`) or the home
+ * directory, so a manifest outside the repository never steers it.
+ * `resolveAgentsDir()` is the one agents-directory chain every loader and bin
+ * uses: explicit option → MELCHIZEDEK_AGENTS_DIR → the manifest's `agents` →
+ * <cwd>/config/agents. A deployed server sets the variable, so the manifest
+ * only changes what a bare command run inside a project finds.
+ *
+ * Imports only node built-ins, zod and lib/paths.ts.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { enginePackageRoot } from './paths.js';
+export const PROJECT_MANIFEST = 'melchizedek.json';
+export const MANIFEST_VERSION = 1;
+/** A path relative to the project root: no absolute paths, no `..` segments. */
+const relPath = z
+    .string()
+    .min(1)
+    .refine((p) => !/^([a-zA-Z]:)?[\\/]/.test(p) && !p.split(/[\\/]/).includes('..'), 'must be relative to the project root and stay inside it');
+const envName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/, 'must be an environment variable name');
+const syndicateRecord = z
+    .object({
+    deliverable: z.enum(['service', 'library', 'mcp']).optional(),
+    publish: z.object({ kind: z.literal('registry'), id: z.string().min(1) }).passthrough().optional(),
+})
+    .passthrough();
+export const projectManifestSchema = z
+    .object({
+    manifest: z.number().int().min(1),
+    engine: z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, 'must be an exact version, e.g. 1.8.0'),
+    agents: relPath,
+    ignore: z.array(z.string().min(1)).optional(),
+    tests: relPath.optional(),
+    env: z.array(envName).optional(),
+    syndicates: z.record(z.string(), syndicateRecord).optional(),
+    registry: z
+        .object({ kind: z.literal('supabase'), url_env: envName.optional(), restart: z.string().optional() })
+        .passthrough()
+        .optional(),
+    production: z
+        .object({ ledger: z.object({ kind: z.literal('postgres'), url_env: envName }).passthrough().optional() })
+        .passthrough()
+        .optional(),
+    tools: z
+        .object({ remote: z.record(z.string(), z.object({ mcp_env: envName }).passthrough()).optional() })
+        .passthrough()
+        .optional(),
+})
+    // Unknown keys are kept: a newer writer's fields survive an older reader.
+    .passthrough();
+/** Thrown for a manifest that does not parse or validate; names the file and fields, never a value. */
+export class ProjectManifestError extends Error {
+    file;
+    issues;
+    constructor(file, issues) {
+        super(`${file}: ${issues.join('; ')}`);
+        this.file = file;
+        this.issues = issues;
+        this.name = 'ProjectManifestError';
+    }
+}
+/**
+ * The nearest folder at or above `from` holding a manifest, without crossing
+ * the repository root or the home directory. Undefined when there is none.
+ */
+export function findProjectRoot(from = process.cwd()) {
+    const home = resolve(homedir());
+    let dir = resolve(from);
+    for (;;) {
+        if (existsSync(join(dir, PROJECT_MANIFEST)))
+            return dir;
+        if (existsSync(join(dir, '.git')) || dir === home)
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Parse and validate a manifest's text. Throws `ProjectManifestError`. */
+export function parseProjectManifest(text, file = PROJECT_MANIFEST) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ProjectManifestError(file, ['not valid JSON']);
+    }
+    const parsed = projectManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new ProjectManifestError(file, parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`));
+    }
+    if (parsed.data.manifest > MANIFEST_VERSION) {
+        throw new ProjectManifestError(file, [`manifest: version ${parsed.data.manifest} is newer than this engine reads (${MANIFEST_VERSION}); upgrade melchizedek-agents`]);
+    }
+    return parsed.data;
+}
+/** A path under the root, or an error when it would leave it. */
+function under(root, rel, field, file) {
+    const abs = resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + sep))
+        throw new ProjectManifestError(file, [`${field}: resolves outside the project root`]);
+    return abs;
+}
+/** Load the project rooted at `root` (the folder holding the manifest). Throws `ProjectManifestError`. */
+export function loadProject(root) {
+    const r = resolve(root);
+    const file = join(r, PROJECT_MANIFEST);
+    const manifest = parseProjectManifest(readFileSync(file, 'utf-8'), file);
+    return {
+        root: r,
+        file,
+        manifest,
+        agentsDir: under(r, manifest.agents, 'agents', file),
+        testsDir: under(r, manifest.tests ?? join('tests', 'agents'), 'tests', file),
+    };
+}
+/** The project at or above `from`, or undefined when there is none. Throws on a broken manifest. */
+export function findProject(from = process.cwd()) {
+    const root = findProjectRoot(from);
+    return root ? loadProject(root) : undefined;
+}
+// The agents-directory chain runs on every syndicate read (an A2A route
+// reads per request), so the manifest lookup is cached per working
+// directory. A broken manifest is cached as "none" and reported by
+// `melchizedek-doctor`, never by a request path.
+const agentsDirCache = new Map();
+/** Forget cached manifest lookups (tests, and an embedder that edits the manifest in-process). */
+export function clearProjectCache() {
+    agentsDirCache.clear();
+}
+function manifestAgentsDir(cwd) {
+    if (!agentsDirCache.has(cwd)) {
+        let dir = null;
+        try {
+            dir = findProject(cwd)?.agentsDir ?? null;
+        }
+        catch {
+            dir = null;
+        }
+        agentsDirCache.set(cwd, dir);
+    }
+    return agentsDirCache.get(cwd) ?? undefined;
+}
+/**
+ * The agents directory: `explicit` → MELCHIZEDEK_AGENTS_DIR → the nearest
+ * manifest's `agents` → <cwd>/config/agents. Always absolute.
+ */
+export function resolveAgentsDir(explicit, env = process.env) {
+    const fromEnv = env.MELCHIZEDEK_AGENTS_DIR?.trim();
+    const cwd = process.cwd();
+    return resolve(explicit ?? (fromEnv || undefined) ?? manifestAgentsDir(cwd) ?? join(cwd, 'config', 'agents'));
+}
+/** Glob to RegExp for `*` (one segment), `**` (any depth) and `?`, on `/`-separated paths. */
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                i++;
+                if (glob[i + 1] === '/') {
+                    i++;
+                    re += '(?:.*/)?';
+                }
+                else
+                    re += '.*';
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+/** True when `relFromRoot` (a `/`-separated path relative to the project root) matches an `ignore` pattern. */
+export function isIgnored(project, relFromRoot) {
+    const p = relFromRoot.split(sep).join('/');
+    return (project.manifest.ignore ?? []).some((g) => globToRegExp(g).test(p));
+}
+/** The syndicate files directly in the agents folder, as names relative to it, minus `ignore`. */
+export function listProjectSyndicates(project) {
+    if (!existsSync(project.agentsDir))
+        return [];
+    const rel = relative(project.root, project.agentsDir);
+    return readdirSync(project.agentsDir)
+        .filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+        .filter((f) => statSync(join(project.agentsDir, f)).isFile())
+        .filter((f) => !isIgnored(project, rel ? `${rel}/${f}` : f))
+        .sort();
+}
+/** The installed engine's package version (no commit suffix). */
+export function enginePackageVersion() {
+    try {
+        const root = enginePackageRoot();
+        if (root)
+            return String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version);
+    }
+    catch {
+        /* fall through */
+    }
+    return '0.0.0';
+}
+/** What is wrong with a project: engine pin, missing folders, stale ignores, unset env names. Never reads a value. */
+export function checkProject(project, running = enginePackageVersion(), env = process.env) {
+    const problems = [];
+    const warnings = [];
+    const pinned = project.manifest.engine;
+    const matches = pinned === running;
+    if (!matches)
+        problems.push(`engine: the project pins melchizedek-agents ${pinned}; ${running} is running`);
+    if (!existsSync(project.agentsDir))
+        problems.push(`agents: ${project.manifest.agents} does not exist`);
+    if (project.manifest.tests && !existsSync(project.testsDir))
+        problems.push(`tests: ${project.manifest.tests} does not exist`);
+    for (const g of project.manifest.ignore ?? []) {
+        if (!anyPathMatches(project.root, globToRegExp(g)))
+            warnings.push(`ignore: "${g}" matches nothing`);
+    }
+    for (const name of project.manifest.env ?? [])
+        if (!env[name]?.trim())
+            warnings.push(`env: ${name} is not set`);
+    const syndicates = listProjectSyndicates(project);
+    for (const f of Object.keys(project.manifest.syndicates ?? {})) {
+        if (!syndicates.includes(f))
+            warnings.push(`syndicates: ${f} is not in ${project.manifest.agents}`);
+    }
+    return { root: project.root, agentsDir: project.agentsDir, engine: { pinned, running, matches }, syndicates, problems, warnings };
+}
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'venv', '.venv', '__pycache__', 'dist']);
+/** Whether any path under root (depth-limited, skipping vendor folders) matches. */
+function anyPathMatches(root, re, rel = '', depth = 0) {
+    if (depth > 6)
+        return false;
+    let entries;
+    try {
+        entries = readdirSync(join(root, rel));
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e))
+            continue;
+        const p = rel ? `${rel}/${e}` : e;
+        if (re.test(p))
+            return true;
+        let dir = false;
+        try {
+            dir = statSync(join(root, p)).isDirectory();
+        }
+        catch {
+            /* unreadable entry */
+        }
+        if (dir && anyPathMatches(root, re, p, depth + 1))
+            return true;
+    }
+    return false;
+}

package/dist/scripts/a2a_server.js

@@ -97,7 +97,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  */
 import { randomBytes } from 'node:crypto';
 import { readdirSync, realpathSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createA2AApp } from '../lib/a2a/app.js';
 import { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, sharedSecret, trustedHeader, } from '../lib/a2a/identity.js';
@@ -116,6 +115,7 @@ import { callbackIdentity, callbackIdentityProblem, oauthServerSetup } from '../
 import { postgresCredentialRows } from '../lib/storage/postgres/credentialStore.js';
 import { setOAuthHosts } from '../lib/tools/oauthHosts.js';
 import { setCredentialHosts } from '../lib/tools/credentialHosts.js';
+import { resolveAgentsDir } from '../lib/project.js';
 // Re-exported for existing importers (tests/failNarration.test.ts).
 export { describeTurnError } from '../lib/a2a/executor.js';
 /** Minimum bearer-secret length below which the server warns. */
@@ -181,7 +181,7 @@ export function servedFileSyndicates(syndicateName, servedAgents, registryAgents
             add(id);
     }
     else {
-        const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+        const agentsDir = resolveAgentsDir();
         let names = [];
         try {
             names = readdirSync(agentsDir);
@@ -633,7 +633,7 @@ if (invokedAsMain) {
         if (error?.code === 'ENOENT') {
             console.error(`[A2A] Syndicate not found: ${arg || 'syndicate.yaml'}.\n`
                 + '      Pass your syndicate: melchizedek-serve <name>.yaml\n'
-                + '      (agents directory: MELCHIZEDEK_AGENTS_DIR, or <cwd>/config/agents)');
+                + '      (agents directory: MELCHIZEDEK_AGENTS_DIR, else the agents folder in melchizedek.json, else <cwd>/config/agents)');
             process.exit(1);
         }
         console.error(error);

package/dist/scripts/doctor.js

@@ -33,6 +33,7 @@ import { loadEnv } from '../lib/loadEnv.js';
 import { checkProblems, renderDoctor, runDoctor } from '../lib/doctor.js';
 import { renderCapabilityMatrix } from '../lib/models/capabilities.js';
 import { assignMemoryNamespace, LEGACY_MEMORY_APP_NAME } from '../lib/memory/namespace.js';
+import { resolveAgentsDir } from '../lib/project.js';
 loadEnv();
 const args = process.argv.slice(2);
 const json = args.includes('--json');
@@ -52,7 +53,7 @@ function packageScripts() {
 if (fixAt !== -1) {
     // ADR 0020: give each named long-term syndicate its own memory namespace.
     // Only the files named are touched; with none named, list the candidates.
-    const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+    const agentsDir = resolveAgentsDir();
     const files = args.slice(fixAt + 1).filter((a) => !a.startsWith('--'));
     if (files.length === 0) {
         const pending = runDoctor({ agentsDir }).syndicates.filter((s) => s.memory && !s.memory.declared && !s.file.includes('/'));

package/dist/scripts/mcp_server.js

@@ -38,6 +38,7 @@
 import { readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { resolveAgentsDir } from '../lib/project.js';
 /** The bin's flags. Throws, naming the flag, on one it does not know. */
 export function parseMcpArgs(argv) {
     const out = { syndicates: [], http: false, help: false };
@@ -160,7 +161,7 @@ export async function startMcpServer(argv = process.argv.slice(2)) {
     const bindings = () => ({
         current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }),
     });
-    const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+    const agentsDir = resolveAgentsDir();
     let files = args.syndicates.map((id) => (id.endsWith('.yaml') || id.endsWith('.yml') ? id : `${id}.yaml`));
     const named = files.length > 0;
     if (!named) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop, Supabase or Postgres session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "./a2a/limits": "./dist/lib/a2a/redisLimits.js",
     "./mcp": "./dist/lib/mcp/server.js",
     "./registry": "./dist/lib/registry.js",
+    "./project": "./dist/lib/project.js",
     "./server": "./dist/scripts/a2a_server.js",
     "./guards": "./dist/lib/guards/index.js",
     "./storage/postgres": "./dist/lib/storage/postgres/index.js",