@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/deploy/preflight.d.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig } from "../harnesses/pi-durable/define.ts";
+import { type EffectiveConfig, type InstanceConfigSource } from "../harnesses/pi-durable/config.ts";
 import { type DeclaredChannel } from "../channels/discover.ts";
 import type { DeclaredSecret } from "../declared-secrets.ts";
 import { type ContainerInput } from "./container.ts";
@@ -27,15 +27,23 @@ interface DeployFacts {
      * ({@link credentialRoute}).
      */
     modelAuth: string | undefined;
+    /**
+     * The variables the model's provider reads its key from, and whether the deployment needs one of them set on its
+     * target: when no key is in the value file and the provider has no login to run on the box, the key is the only way in.
+     */
+    modelKey: {
+        variables: string[];
+        required: boolean;
+    };
     /**
      * The provider the deployment must log in to itself (`fastagent login --deployment`): the model's credential does
      * not travel, because it is neither a variable in the value file nor resolved by the definition's own provider code.
      * Nothing from this machine's credentials file is ever copied, so a login on the box is its only holder.
      */
     boxLogin: string | undefined;
-    /** Every declaration the definition makes — the names the value file must supply, by declaring file. */
-    declaredSecrets: DeclaredSecret[];
-    /** The runbook's variable list: the declared names, then everything else the value file carries. */
+    /** Every declaration the definition makes — the names the target must hold, by declaring file. */
+    declaredSecrets: readonly DeclaredSecret[];
+    /** The runbook's variable list: the declared names, each hinted by the file that declared it. */
     secrets: DeploymentSecret[];
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */
     container: ContainerInput;
@@ -59,7 +67,12 @@ export interface DeployReport {
 }
 interface PreflightInput {
     agentDir: string;
-    config: AgentConfig;
+    config: EffectiveConfig;
+    /** The instance configuration this deployment delivers (`--config`): as read, and its file's text. */
+    delivered?: {
+        source: InstanceConfigSource;
+        text: string;
+    };
     /** `--run` fully deploys, so a definition that resolves NO model is a GATE (a known crash-loop); else it warns. */
     run: boolean;
     /** `--force` regenerates the artifacts fastagent OWNS, so a kept `.dockerignore`'s content checks do not apply. */

package/dist/deploy/preflight.js

@@ -8,42 +8,78 @@ import { basename, join, relative } from "node:path";
 import { isModelSpec, isReleaseAgentName } from "./workspace.js";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { resolveAuthPath } from "../harnesses/models/credentials.js";
-import { environmentAuth, interactiveLoginKind, loginProviders, modelsOver, providerOf, } from "../harnesses/models/models.js";
+import { environmentAuth, interactiveLoginKind, keyVariables, listModels, loginProviders, modelHint, modelsOver, providerOf, } from "../harnesses/models/models.js";
 import { modelEnvironment } from "../harnesses/models/environment.js";
-import { buildDefinitionShape, definitionSecrets, prepareDefinition, } from "../harnesses/pi-durable/open.js";
-import { LOCAL_CONTEXT_FILE, exists } from "../paths.js";
+import { projectInstanceConfig, } from "../harnesses/pi-durable/config.js";
+import { definitionSecrets } from "../harnesses/pi-durable/definition.js";
+import { buildDefinitionShape, loadSourceDefinition } from "../harnesses/pi-durable/open.js";
+import { INSTANCE_CONFIG_FILE, exists } from "../paths.js";
 import { channelIngress } from "../channels/discover.js";
 import { loadContent, loadEnvironment } from "../content/file.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { RUNTIME_FLOOR, belowFloor, detectRuntime, listsFastagent, readPackageJson } from "../runtime.js";
-import { fastagentVersion } from "../version.js";
-import { isGeneratedDockerfile } from "./container.js";
+import { DELIVERED_CONFIG_DIR, isGeneratedDockerfile } from "./container.js";
+import { deliveredTextProblem } from "./delivered-text.js";
+import { declareMcp, literalCredentialAdvice, literalCredentials, relativeCommands, } from "../mcp/config.js";
 import { buildContextPaths, checkKeptIgnoreFiles } from "./build-context.js";
 import { dotEnvPath, loadEnvValues } from "../value-file.js";
 import { deploymentSecrets, isEnvKey } from "./secrets.js";
 import { DEFAULT_HTTP_PORT } from "../service.js";
 import { declaredVariables, declaresTool, runtimeAdvice } from "../environment/declare.js";
 import { checkPackages, MISE_PACKAGE_NAMES, miseBinary, packageSpecs } from "../environment/mise.js";
+/** What a host's clone of a `github` entry reads; optional, since a public repository needs none. */
+const GITHUB_TOKEN_SECRET = {
+    name: "GITHUB_TOKEN",
+    declaredIn: "context.json (a github content entry)",
+    description: "git's credential for a private repository, and for the agent to push",
+    optional: true,
+};
+/**
+ * The MCP servers the box will open: the program's, in the image, and the delivered configuration's. A name both
+ * declare, or one that cannot be read, is an issue (the box would refuse to open); a literal credential is a warning,
+ * since it ships in the image and FastAgent cannot tell a secret from a setting; a relative stdio command in the
+ * delivered configuration is an issue, since nothing delivers the script it names. (The program's own is relative to
+ * its package, and `build` refuses one that it does not copy.)
+ * `args` are not checked: FastAgent cannot know which strings are paths. Answers whether the list reads.
+ */
+function checkMcp(agentDir, delivered, report) {
+    let declarations;
+    try {
+        declarations = declareMcp(agentDir, delivered);
+    }
+    catch (error) {
+        report.issue(messageOf(error));
+        return false;
+    }
+    for (const literal of literalCredentials(declarations)) {
+        report.warn(`${literal.file} mcpServers.${literal.server}.${literal.field}.${literal.key} is a literal value, and this ` +
+            `deploy puts it in the image: ${literalCredentialAdvice(literal)} and set that name with ` +
+            `\`fastagent secrets set <host> <NAME>\``);
+    }
+    for (const { name, file, command } of relativeCommands(declarations).filter(({ origin }) => origin === "instance")) {
+        report.issue(`${file} mcpServers.${name}: the command "${command}" is a relative path, and a deploy delivers the configuration ` +
+            `but not the script it names: write an absolute path on the box, or a command found on its PATH`);
+    }
+    return true;
+}
 /**
  * What each content entry becomes on the host, one line each, so none is missing there unsaid (agent-model.md §3). A
- * repository `context.json` declares is cloned there, as on this machine without a checkout bound. A directory only
- * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. It
- * is a warning, since the deployed agent lacks data it was meant to work on.
+ * repository, the program's or the delivered configuration's, is cloned there. A directory of this machine is not on
+ * the host, and FastAgent maps none onto it, so the delivered configuration naming one is an issue: the deployed agent
+ * would lack data it was configured to work on.
  */
-function checkContent({ declared, bound }, storageResets, report) {
+function checkContent(declared, delivered, storageResets, report) {
+    const fate = storageResets
+        ? "cloned afresh on every deployment, since the host's storage starts over; what the agent did not push is lost"
+        : "cloned on the host, and brought up to date in place at each start";
     for (const entry of declared) {
-        const fate = storageResets
-            ? "cloned afresh on every deployment, since the host's storage starts over; what the agent did not push is lost"
-            : "cloned on the host, and brought up to date in place at each start";
-        report.note(`works on ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
-    }
-    for (const binding of bound) {
-        if (binding.kind !== "local")
+        if (entry.kind === "github") {
+            report.note(`works on ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
             continue;
-        const stays = `works on ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
-            `${LOCAL_CONTEXT_FILE}), stays here, and the deployed agent works without it`;
-        report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo, or copy ` +
-            `what it only needs to read there into the agent directory, which every release carries`);
+        }
+        report.issue(`works on ${entry.name}: a directory of this machine (${entry.path}), in ${delivered}, which the host does not ` +
+            `have: declare a repository instead (github:owner/repo), or copy what the agent only needs to read into the ` +
+            `agent directory, which every release carries`);
     }
 }
 /**
@@ -52,12 +88,12 @@ function checkContent({ declared, bound }, storageResets, report) {
  * the agent's mise cannot check them, which is an issue (a warning without `--run`), as a code input that cannot load
  * is.
  */
-async function checkEnvironment(agentDir, packages, hasPackageJson, pkg, report) {
+async function checkEnvironment(agentDir, packages, pkg, report) {
     if (Object.keys(packages).length === 0)
         return;
     const linux = MISE_PACKAGE_NAMES.filter((name) => name.includes("-linux-"));
     const missing = linux.filter((name) => !(name in (pkg.optionalDependencies ?? {})));
-    if (!hasPackageJson || missing.length > 0) {
+    if (missing.length > 0) {
         report.issue(`context.json declares packages, and the image would have no mise to install them with: the agent's ` +
             `package.json does not list ${missing.join(", ")}. Run \`fastagent env install\` in the agent directory.`);
         return;
@@ -103,7 +139,7 @@ export async function preflightDeploy(input) {
     }
 }
 async function gatherFacts(input, report) {
-    const { agentDir, config, force, noResidentProcess, storageResets = false, servesApi = false } = input;
+    const { agentDir, config, delivered, force, noResidentProcess, storageResets = false, servesApi = false } = input;
     // The release manifest carries this name into the container, where it is joined onto the storage root — so `init`'s
     // "one path segment" is not enough here.
     if (!isReleaseAgentName(basename(agentDir))) {
@@ -111,13 +147,28 @@ async function gatherFacts(input, report) {
             `may use only letters, digits, "-" and "_"; rename it (the fastagent.config.ts inside is what ` +
             `makes it an agent, never its name)`);
     }
-    const content = loadContent(agentDir);
-    checkContent(content, storageResets, report);
+    // A deployed agent is built (`start` opens `dist/`), and a build needs the project's own manifest and TypeScript.
+    if (!(await exists(join(agentDir, "package.json")))) {
+        throw new DeployGate(`the agent directory has no package.json, and a deployed agent is built: \`fastagent build\` needs one with ` +
+            `"type": "module" and typescript (\`fastagent init\` writes both)`);
+    }
+    const content = loadContent(agentDir, delivered?.source);
+    checkContent(content, delivered?.source.label, storageResets, report);
+    const textProblem = delivered === undefined ? undefined : deliveredTextProblem(agentDir, delivered.source);
+    if (textProblem !== undefined)
+        report.issue(textProblem);
+    const mcpOpens = checkMcp(agentDir, delivered?.source, report);
+    // The project's own, the development instance's: a deploy carries only the configuration it is given.
+    const own = await projectInstanceConfig(agentDir);
+    if (own !== undefined && own.label !== delivered?.source.label) {
+        report.note(`${INSTANCE_CONFIG_FILE} is the development instance's configuration and a deploy does not carry it` +
+            (delivered === undefined ? ": pass --config <file> to deliver one" : `; it carries ${delivered.source.label}`));
+    }
     // The definition the box will load on every start, read here first: a refusal in it (a module that fails to import,
     // two tools under one name) builds a perfectly good image that crash-loops on fly/railway/docker and fails every
     // invocation on AgentCore. This is the boundary that turns that refusal into a deploy finding, so the error is
     // carried whole into the issue rather than rethrown.
-    const definition = await prepareDefinition(agentDir).catch((error) => {
+    const definition = await loadSourceDefinition(agentDir).catch((error) => {
         report.issue(`the definition does not load, so the deployed agent would not start: ${messageOf(error)}`);
         return undefined;
     });
@@ -125,11 +176,12 @@ async function gatherFacts(input, report) {
     // cannot disagree about it.
     const valueFile = relative(agentDir, dotEnvPath(agentDir));
     const values = loadEnvValues(dotEnvPath(agentDir));
-    // A host has no credential of the author's: what it clones with is GITHUB_TOKEN, which travels like every value.
-    if (content.declared.length > 0 && !values.get("GITHUB_TOKEN")) {
-        report.note(`no GITHUB_TOKEN in ${valueFile}: the host clones without a credential, which reaches public repositories ` +
-            `only, and the agent cannot push from its clones. Set one there to give it access; it travels with the ` +
-            `other values`);
+    // A host has no credential of the author's: what it clones with is GITHUB_TOKEN, a value of the target like any other.
+    // This reads this machine's file only, so a target that already holds one is told as much.
+    if (content.length > 0 && !values.get("GITHUB_TOKEN")) {
+        report.note(`no GITHUB_TOKEN in ${valueFile}: unless the target holds one, the host clones without a credential, which ` +
+            `reaches public repositories only, and the agent cannot push from its clones. \`fastagent secrets set <host> ` +
+            `GITHUB_TOKEN\` gives it access`);
     }
     const model = resolveDeployModel(config, values, valueFile);
     if (model.invalid !== undefined) {
@@ -138,7 +190,7 @@ async function gatherFacts(input, report) {
         throw new DeployGate(`the model in ${model.source} is not a "provider/modelId" spec: ${JSON.stringify(model.invalid)}`);
     }
     if (!model.spec) {
-        const issue = `no model resolves for this deployment — set \`model: "provider/id"\` in fastagent.config.ts (it travels ` +
+        const issue = `no model resolves for this deployment — set \`defaults: { model: "provider/id" }\` in fastagent.config.ts (it travels ` +
             `in the image), or FASTAGENT_MODEL in ${valueFile} (deploy records that one in the release manifest)` +
             // Whoever has the variable set right here sees `fastagent info` report a model, so "no model resolves" reads
             // like a bug until the message says which environment was read. It states that fact WITHOUT attributing the
@@ -154,8 +206,14 @@ async function gatherFacts(input, report) {
         report.note(`model ${model.spec} (source: ${model.source})`);
     }
     const modelSpec = model.spec;
-    const declaredSecrets = definition ? definitionSecrets(definition) : declaredVariables(loadEnvironment(agentDir));
-    const code = definition ? buildShapes(definition, values, report) : undefined;
+    const declaredSecrets = [
+        ...(definition
+            ? definitionSecrets(definition, config, mcpOpens ? delivered?.source : undefined)
+            : declaredVariables(loadEnvironment(agentDir))),
+        // The host's clone of a github entry reads it, so `secrets list|push|set` and `deploy` know the name.
+        ...(content.some((entry) => entry.kind === "github") ? [GITHUB_TOKEN_SECRET] : []),
+    ];
+    const code = definition ? buildShapes(definition, values, config, report) : undefined;
     const channels = [...(code?.channels ?? [])].map(([name, module]) => ({
         name,
         ingress: channelIngress(module),
@@ -163,7 +221,7 @@ async function gatherFacts(input, report) {
     for (const { name, ingress } of channels) {
         if (CHANNEL_KINDS.includes(name))
             continue;
-        const secretsPart = `its variables travel from ${valueFile} like every other`;
+        const secretsPart = `the variables it declares are the target's to hold (\`fastagent secrets\`), like every other`;
         report.note(ingress === "long-connection"
             ? `long-connection channel "${name}" is custom — ${secretsPart}; generated deploy plans keep the process running and skip webhook registration`
             : `route channel "${name}" is custom — ${secretsPart}; configure its webhook yourself`);
@@ -195,19 +253,24 @@ async function gatherFacts(input, report) {
             valueFile,
         });
     }
+    const modelProvider = modelSpec ? loginProviders(providers).find((p) => p.id === providerOf(modelSpec)) : undefined;
+    const modelKey = {
+        variables: modelProvider ? await keyVariables(modelProvider) : [],
+        required: boxLogin !== undefined && !hasLogin(boxLogin, providers),
+    };
     if (boxLogin !== undefined) {
-        if (!hasLogin(boxLogin, providers)) {
-            report.issue(`no credential for ${modelSpec} reaches the deployment, and "${boxLogin}" has no login to run there — set ` +
-                `its API key in ${valueFile}`);
+        if (modelKey.required) {
+            report.note(`${modelSpec}: "${boxLogin}" has no login to run on the box, so its API key (${modelKey.variables.join(" or ")}) ` +
+                `must be set on the target`);
         }
         else {
             report.note(`${modelSpec}: no credential ships with this deploy (this machine's logins and shell stay here) — once the ` +
                 `box is up, \`--run\` asks it: it keeps what it already authenticates ${boxLogin} with, else logs in ` +
-                `(\`fastagent login ${boxLogin} --deployment\`). Or set ${boxLogin}'s API key in ${valueFile}`);
+                `(\`fastagent login ${boxLogin} --deployment\`). Or set ${boxLogin}'s API key on the target ` +
+                `(\`fastagent secrets set <host> ${modelKey.variables[0] ?? "<KEY_NAME>"}\`)`);
         }
     }
     // Container facts (shared by every host) + the warnings that follow.
-    const hasPackageJson = await exists(join(agentDir, "package.json"));
     const pkg = await readPackageJson(agentDir);
     const { runtime, bunVersion, hasLockfile } = detectRuntime(agentDir, pkg);
     const kept = await keptDockerfile(agentDir);
@@ -226,18 +289,13 @@ async function gatherFacts(input, report) {
         ((await exists(join(agentDir, "pnpm-lock.yaml"))) || (await exists(join(agentDir, "yarn.lock"))));
     // Does the baked agent directory ship a `.git`?
     const shipsGit = await exists(join(agentDir, ".git"));
-    // After the facts: the deps sentence must match the agent's actual shape (a markdown-only agent has no package.json
-    // and installs nothing — the note must not point at a file that doesn't exist).
-    const deps = hasPackageJson
-        ? `its package.json dependencies are installed in the image`
-        : `the agent has no package.json, so no deps are installed (the pinned global CLI serves the directory)`;
     // What a RELEASE does — host-neutral, because how long the storage under it lives is the host's own answer and its
     // runbook gives it (a Fly volume outlives every deploy; AgentCore's mount does not).
     report.note(`the agent directory is baked as the definition (WYSIWYG — what you see is what ships, git or not, clean or ` +
-        `not); ${deps}. Every release replaces the deployed definition and leaves the instance's state and ` +
-        `credentials in place — for how long, see this host's storage note below`);
+        `not); its package.json dependencies are installed in the image. Every release replaces the image and leaves the instance's working directory, state and ` +
+        `credentials in place on the storage — for how long, see this host's storage note below`);
     // A code agent with no lockfile builds via a non-frozen install (ranges resolve at build time) — not reproducible.
-    if (hasPackageJson && !hasLockfile) {
+    if (!hasLockfile) {
         const lock = runtime === "bun" ? "bun.lock" : "package-lock.json";
         report.warn(hasOtherLock
             ? `the generated Dockerfile is npm-based — your pnpm/yarn lockfile is NOT used (build runs ` +
@@ -246,7 +304,7 @@ async function gatherFacts(input, report) {
                 `Run \`${install}\` and commit the lockfile for pinned redeploys.`);
     }
     // The code-path Dockerfile runs `${runner}`.
-    if (hasPackageJson && !listsFastagent(pkg)) {
+    if (!listsFastagent(pkg)) {
         report.warn(`package.json does not list @fastagent-sh/fastagent — the image's \`${runner}\` has no local bin to run, ` +
             `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`);
     }
@@ -254,12 +312,12 @@ async function gatherFacts(input, report) {
     await checkKeptIgnoreFiles({ agentDir, force, paths }, report);
     const environment = loadEnvironment(agentDir);
     const packages = environment?.packages ?? {};
-    await checkEnvironment(agentDir, packages, hasPackageJson, pkg, report);
+    await checkEnvironment(agentDir, packages, pkg, report);
     const installsPackages = Object.keys(packages).length > 0;
     // Write-back mechanics are fastagent's (the policy is the agent's prompt's). A repository content entry is cloned on the
     // host, which takes git too. mise downloads over TLS, and the slim base image has no CA certificates; rustup, which
     // mise installs rust with, downloads with curl. The agent's own apt packages join them, in one layer.
-    const needsGit = shipsGit || content.declared.length > 0;
+    const needsGit = shipsGit || content.length > 0;
     const apt = [
         ...new Set([
             ...(needsGit ? ["git"] : []),
@@ -272,30 +330,30 @@ async function gatherFacts(input, report) {
         releaseId: randomUUID(),
         agent: basename(agentDir),
         machineryPaths: paths.machineryPaths,
-        hasPackageJson,
         runtime,
         bunVersion,
         hasLockfile,
-        version: await fastagentVersion(),
         apt,
         ...(installsPackages ? { packages: packageSpecs(packages) } : {}),
         ...(model.envValue !== undefined ? { modelSpec: model.envValue } : {}),
+        ...(delivered !== undefined ? { config: delivered.text } : {}),
         shipsGit,
     };
     const port = config.http?.port ?? DEFAULT_HTTP_PORT;
     if (kept !== undefined)
-        checkKeptDockerfile(kept, agentDir, model.envValue, valueFile, report);
+        checkKeptDockerfile(kept, agentDir, model.envValue, valueFile, delivered !== undefined, report);
     return {
         channels,
         hasCron,
         values,
         valueFile,
         modelAuth,
+        modelKey,
         boxLogin,
         container,
         port,
         declaredSecrets,
-        secrets: deploymentSecrets(modelAuth, declaredSecrets, values, valueFile),
+        secrets: deploymentSecrets(modelAuth, declaredSecrets),
     };
 }
 /**
@@ -303,9 +361,9 @@ async function gatherFacts(input, report) {
  * deploy runs on a machine that may hold none of them, and whether the value file supplies them is the values gate's
  * question, asked by name. A build that fails is an issue, as a module that fails to load is.
  */
-function buildShapes(definition, values, report) {
+function buildShapes(definition, values, config, report) {
     try {
-        return buildDefinitionShape(definition, Object.fromEntries(values));
+        return buildDefinitionShape(definition, Object.fromEntries(values), config);
     }
     catch (error) {
         report.issue(`the definition does not build, so the deployed agent would not start: ${messageOf(error)}`);
@@ -343,8 +401,8 @@ async function checkModelExists(agentDir, spec, providers, report, box) {
             `as on a first deploy, fetches it from pi.dev as it starts, and refuses to start on "${spec}" if it cannot`);
         return;
     }
-    report.issue(`no provider of the deployed agent offers "${spec}" — pi-ai's built-ins, pi's published catalog and the ` +
-        `providers fastagent.config.ts declares are all it has`);
+    report.issue(`no provider of the deployed agent offers "${spec}": ${modelHint(listModels(models), spec)}. Its providers are ` +
+        `pi-ai's built-ins, pi's published catalog and the ones fastagent.config.ts declares`);
 }
 /**
  * HOW THE MODEL'S CREDENTIAL REACHES THE BOX, from what the deploy ships and nothing else. The box is the one authority
@@ -391,14 +449,22 @@ async function keptDockerfile(agentDir) {
  */
 function checkKeptDockerfile(dockerfileText, agentDir, 
 /** The model the release manifest carries (set only when the value file named it). */
-modelFromValueFile, valueFile, report) {
-    // What the image installs: the packages and apt packages. Variables travel with the value file, whatever the image.
+modelFromValueFile, valueFile, 
+/** The release delivers an instance configuration, which the image must copy and name. */
+deliversConfig, report) {
+    // What the image installs: the packages and apt packages. Variables are the target's, whatever the image.
     const environment = loadEnvironment(agentDir);
     if (Object.keys(environment?.packages ?? {}).length > 0 || (environment?.aptPackages.length ?? 0) > 0) {
         report.warn(`kept your hand-written Dockerfile — it installs the environment context.json declares only if it says so: ` +
             `a generated Dockerfile shows the layers (the apt packages, then \`mise install --system\` of the packages ` +
             `context.json declares).`);
     }
+    // `start` opens dist/. Docker and Fly upload the directory as it is, but `railway up` follows .gitignore, which the
+    // scaffold gives `/dist`: without a build step of its own the image has none, and the box does not start.
+    if (!/\bfastagent(?:\s+run)?\s+build\b|\bnpm\s+run\s+build\b/.test(dockerfileText)) {
+        report.warn(`your Dockerfile does not run \`fastagent build\`: \`start\` opens dist/, which an upload that follows ` +
+            `.gitignore (Railway) leaves out. Add \`RUN ./node_modules/.bin/fastagent build\` after copying the agent.`);
+    }
     // The INSTRUCTION is the question, not the file's authorship: `prepareStartWorkspace` returns early without
     // FASTAGENT_RELEASE_FILE, so a Dockerfile that sets it reads the manifest whoever wrote it. This gates rather
     // than warns because it is about FastAgent's OWN delivery arriving — the model would be reported here and
@@ -406,12 +472,18 @@ modelFromValueFile, valueFile, report) {
     // Anywhere in an `ENV` instruction, not just first: `ENV A=1 FASTAGENT_RELEASE_FILE=/app/x` is ordinary
     // Dockerfile style and hard-refusing it would be a false gate. A backslash continuation still reads as absent
     // (covering it means joining lines first) — the remaining over-strict edge.
-    if (modelFromValueFile !== undefined && !/^\s*ENV\s[^\n]*\bFASTAGENT_RELEASE_FILE[=\s]/m.test(dockerfileText)) {
+    const readsManifest = /^\s*ENV\s[^\n]*\bFASTAGENT_RELEASE_FILE[=\s]/m.test(dockerfileText);
+    if (modelFromValueFile !== undefined && !readsManifest) {
         const issue = `your Dockerfile does not set FASTAGENT_RELEASE_FILE, and the model comes from ${valueFile} — it travels ` +
             `in the release manifest, which is only read when that ENV points at it. Add it (see a generated ` +
-            `Dockerfile), or set \`model\` in fastagent.config.ts so it ships in the config instead.`;
+            `Dockerfile), or set \`defaults.model\` in fastagent.config.ts so it ships in the config instead.`;
         report.issue(issue);
     }
+    if (deliversConfig && !/^\s*ENV\s[^\n]*\bFASTAGENT_CONFIG[=\s]/m.test(dockerfileText)) {
+        report.issue(`your Dockerfile does not set FASTAGENT_CONFIG, and --config delivers the instance configuration in the ` +
+            `image, which \`start\` reads only where that ENV points: copy ${DELIVERED_CONFIG_DIR}/ into the image and set it ` +
+            `(see a generated Dockerfile).`);
+    }
 }
 /**
  * WHICH model this deployment runs on, and where that came from.

package/dist/deploy/railway/ignore.d.ts

@@ -0,0 +1,8 @@
+export declare const RAILWAYIGNORE_FILE = ".railwayignore";
+export declare function isGeneratedRailwayignore(content: string): boolean;
+export declare function railwayignore(): string;
+/**
+ * Why a `.railwayignore` the author kept would leave the deploy's own directory out of the upload, so the image build
+ * could not copy it, or undefined when it lets it through (or there is none to keep).
+ */
+export declare function keptRailwayignoreProblem(agentDir: string): string | undefined;

package/dist/deploy/railway/ignore.js

@@ -0,0 +1,57 @@
+/**
+ * What `railway up` uploads. It follows `.gitignore`, and only inside a git repository, so a project without one would
+ * upload its credentials, and one with one would drop `.fastagent/deploy/`, which `.gitignore` ignores and the image is
+ * built from. `.railwayignore` outranks `.gitignore`; a parent that is ignored hides its children, hence the three
+ * lines for the one directory (verified against Railway, which reads the same patterns as ripgrep).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import ignore from "ignore";
+import { DELIVERED_CONFIG_DIR } from "../container.js";
+export const RAILWAYIGNORE_FILE = ".railwayignore";
+const MARKER = "# Generated by `fastagent deploy railway`";
+export function isGeneratedRailwayignore(content) {
+    return content.startsWith(MARKER);
+}
+export function railwayignore() {
+    return `${MARKER}. Delete this line to take ownership (deploy then keeps your file).
+# Credentials, state and clones never leave this machine, whatever .gitignore says.
+.secrets
+.state
+/content
+.env
+.env.*
+!.env.example
+# The deploy's own directory is what the image is built from, and .gitignore ignores .fastagent.
+!.fastagent
+.fastagent/*
+!${DELIVERED_CONFIG_DIR}
+`;
+}
+function readIfExists(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+/**
+ * Why a `.railwayignore` the author kept would leave the deploy's own directory out of the upload, so the image build
+ * could not copy it, or undefined when it lets it through (or there is none to keep).
+ */
+export function keptRailwayignoreProblem(agentDir) {
+    const kept = readIfExists(join(agentDir, RAILWAYIGNORE_FILE));
+    if (kept === "" || isGeneratedRailwayignore(kept))
+        return undefined;
+    const upload = ignore()
+        .add(readIfExists(join(agentDir, ".gitignore")))
+        .add(kept);
+    if (!upload.ignores(`${DELIVERED_CONFIG_DIR}/fastagent.json`))
+        return undefined;
+    return (`your ${RAILWAYIGNORE_FILE} (kept), with .gitignore, leaves ${DELIVERED_CONFIG_DIR}/ out of what \`railway up\` ` +
+        `uploads, and the image is built from it. Add \`!.fastagent\`, \`.fastagent/*\` and \`!${DELIVERED_CONFIG_DIR}\` ` +
+        `to it, or delete it to let deploy generate one.`);
+}

package/dist/deploy/railway/plan.d.ts

@@ -16,8 +16,7 @@ export interface RailwayPlanInput extends ContainerInput {
      */
     channels: readonly DeclaredChannel[];
     /**
-     * The runbook's variable list (`deploymentSecrets`): what must have a value, then everything else the value file
-     * carries.
+     * The runbook's variable list (`deploymentSecrets`): the declared names, each hinted by the file that declared it.
      */
     secrets?: readonly DeploymentSecret[];
     /** `schedules/` declares a schedule — one of the things that forbids App Sleeping (deploy/residency.ts). */

package/dist/deploy/railway/plan.js

@@ -2,21 +2,23 @@ import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts, imageHasGit } from "../container.js";
 import { deploymentLoginCommand } from "../box-shell.js";
 import { WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
+import { RAILWAYIGNORE_FILE, railwayignore } from "./ignore.js";
+import { stripEdges } from "../../strip-edges.js";
 /** State root = the volume mount path, kept in lockstep. */
 const MOUNT = "/data";
 /** The name this tool gives BOTH the project and the service, derived from the agent directory's name. */
 export function toRailwayName(basename) {
-    return basename.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+    return stripEdges(basename.replace(/[^a-zA-Z0-9-]+/g, "-"), (char) => char === "-") || "agent";
 }
 /** Compute the Railway deploy plan from the resolved definition. */
 export function planRailwayDeploy(input) {
     const { serviceName, channels } = input;
-    const artifacts = containerArtifacts(input);
+    const artifacts = [...containerArtifacts(input), { path: RAILWAYIGNORE_FILE, content: railwayignore() }];
     const secrets = input.secrets ?? [];
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and variables are
     // service-scoped and `railway up` deploys THE service.
     const runbook = [
-        `# Deploy to Railway. Dockerfile(.dockerignore) are generated above.`,
+        `# Deploy to Railway. Dockerfile(.dockerignore, .railwayignore) are generated above.`,
         `# Prereqs: the Railway CLI (https://docs.railway.com/guides/cli) and \`railway login\`.`,
         ``,
         `# One-time setup (init → service → volume → variables). Skip it on redeploy: repeating it creates`,
@@ -38,14 +40,14 @@ export function planRailwayDeploy(input) {
         `railway variables set FASTAGENT_STATE_DIR=${MOUNT}/.state FASTAGENT_SECRETS_DIR=${MOUNT}/.secrets`,
     ];
     if (secrets.length > 0) {
-        runbook.push(`# Secrets:`, `#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+        runbook.push(`# Secrets the service needs a value for. \`fastagent secrets push railway\` sets the ones a value file holds and`, `# \`fastagent secrets set railway <NAME>\` one typed without echo; or with the railway CLI:`, `#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
     runbook.push(``, `# Before a new definition release, run \`fastagent deploy railway\` to refresh the release manifest.`, `# Upload the agent directory and build on Railway (no local Docker needed): Railway builds the`, `# Dockerfile at its root. It marks the deploy live once the container starts, without waiting for`, `# /health: \`railway logs\` shows a box that crashes on boot.`, `railway up`);
     // The credential is created on the box, never carried: the box is then the only holder of its grant.
     if (input.boxLogin) {
         runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from the agent directory):`, `${deploymentLoginCommand("railway", input.boxLogin)}`);
     }
-    runbook.push(``, `# The volume keeps .state and .secrets across restarts and deploys; each release replaces /data/definition.`, input.shipsGit
+    runbook.push(``, `# The volume is the agent's working directory: it keeps its work, .state and .secrets across restarts and deploys.`, input.shipsGit
         ? `# Railway uploads may strip .git, so the deployed definition may have no history.`
         : imageHasGit(input)
             ? `# Git is installed (github content is cloned here, or context.json declares it in aptPackages).`
@@ -53,7 +55,7 @@ export function planRailwayDeploy(input) {
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev).
     const steps = webhookRunbook(`https://<your-domain>`, channels);
     if (steps.length > 0) {
-        runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`, ...steps);
+        runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`, `# Or, before \`railway up\`, set it as http.publicUrl in the configuration \`deploy --config\` delivers, and`, `# re-run \`fastagent deploy railway\`: the box then points Telegram, Feishu and Lark there itself.`, ...steps);
     }
     // Scale-to-zero: App Sleeping is dashboard-only (no CLI/API) — a manual step, not a generated setting. WHY it is
     // forbidden is residency.ts's to decide; the SETTING and the path through the dashboard are Railway's.