auggy 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-05-12
+
+The deployable-runtime release. First npm-installable Auggy CLI with shipped feature set (0.3.0 was a name-claim publish with no functional changes). End-to-end Railway deployment support and a structural eval suite for the layered-memory autoSave path.
+
+### Added
+
+#### Deployment
+
+- **`auggy deploy <name> --to railway` command.** Ships an agent to Railway end-to-end: presence + auth checks, bundle staging with secure exclusions (`.env`, `*.db*`, `workspace/`, `node_modules/`, `.git/`, `.worktrees/`, `.claude/`, `.DS_Store`, `*.tmp`), Dockerfile + entrypoint generation, `railway link`, `railway volume add` (one-time, mounted at `/app/data`), `railway domain --generate`, secrets push including `AUGGY_PUBLIC_URL`, then `railway up`. Redeploys reuse the existing `CloudRecord` from `~/.auggy/agents.json` for idempotency. (See `docs/18-deploy.md`, ADR-021.)
+- **`auggy remove <name> --cloud` flag.** Destroys the Railway service alongside the local index entry. Tolerates Railway destruction failures with a warning — local cleanup proceeds regardless.
+- **`agent-index` cloud mutators.** `setCloud(name, record)` + `clearCloud(name)` with the same atomic-write + advisory-lock discipline as `addAgent` / `removeAgent`. Cloud state persists in `~/.auggy/agents.json` per the existing `CloudRecord` type.
+- **Operator deployment guide** (`docs/18-deploy.md`) — prerequisites, first-deploy + redeploy flows, autoSave cost surface guidance (citing the new eval suite), persistent state contract, visitorAuth's `${AUGGY_PUBLIC_URL}` interpolation, tear-down, troubleshooting.
+- **npm publish workflow** (`.github/workflows/publish.yml`) — publishes `auggy` to npm on `v*.*.*` tag push. Runs tests + typecheck + version-matches-tag check before `npm publish --provenance --access public`. Uses `NPM_TOKEN` secret.
+
+#### Quality
+
+- **`evals/layered-memory/` integration eval suite.** Seven fixtures × seven structural graders measure end-to-end autoSave behavior under real `agent.inject()` machinery: `factual-recall`, `peer-isolation`, `prompt-rendering`, `cost-overhead`, `false-extract`, `cross-session-recall` (multi-session persistence headliner), and `cross-identity-promotion` (anon → recognized flush). Mock-mode runner is deterministic, no API key required, <100ms. Live Haiku smoke (`evals/layered-memory/smoke.ts`) validates end-to-end against a real model with seven pass criteria at ~$0.005 spend. (See `evals/layered-memory/README.md`.)
+- **`extractJsonArray` JSON extractor.** Replaces the strict `JSON.parse` in `src/augments/layered-memory/extractor/parse.ts` with balanced-bracket extraction — structurally robust to any model wrapper style (markdown fences, leading/trailing prose, language tags, single-line layout, CRLF, escaped quotes, nested objects). Closed the 100% extraction-failure rate on Haiku 4.5 caught by the smoke test.
+
+### Changed
+
+- **`auggy --version`** now reads from `package.json` instead of a hardcoded string. Eliminates the drift class that surfaced after the first npm publish.
+
+### Process
+
+- **First npm publish.** `auggy` is now available via `npm i -g auggy`. Distribution pattern matches Wrangler / Vercel: install → create → dev/start/deploy.
+
+## [0.3.0] - 2026-05-12
+
+Name-claim release. Same code as `c15d3cb` + `@auggy/link@0.1.2` bump. Published manually to claim the unscoped `auggy` package name on npm; no functional changes vs. the prior `0.2.0` release.
+
+## [0.2.0-pre] (pre-OSS items, now folded into 0.4.0)
+
+Items below shipped during the pre-OSS phase and are functionally part of 0.4.0 in the OSS distribution. Kept here for historical reference:
+
 ### Architecture
 
 - **ADR-030 — model-facing skill surface separation.** The three Auggy primitives now surface to the engine on three orthogonal channels: **tools** (eager full schema in `tools[]`), **skills** (new built-in `skills` augment emits one system-placement context block sourced from each SKILL.md's YAML frontmatter, body on-demand via `fs_read`), and **augments** (invisible to the model). `{SKILL_MANIFEST}` is gone from `src/scaffold-templates/identity.md`; `scaffold-skills.ts` shed `buildSkillManifest` + `TOOL_INVENTORY`; `src/cli/skill-manifest.ts` is deleted; the kernel context allocator no longer wraps blocks with `[AUGMENT CONTEXT: <source>]` (the augment-name attribution is suppressed pre-send, preserved only in operator-facing trace data). The 8 bundled SKILL.md files already shipped agentskills.io-compatible frontmatter. `auggy create` default-mounts the new `skills` augment.

package/README.md

@@ -20,8 +20,8 @@ Auggy (augment-1) is a modular agent runtime in TypeScript/Bun, purpose-built fo
 ## Quick start
 
 ```bash
-# Install dependencies
-bun install
+# Install the CLI globally (requires Bun: https://bun.sh/install)
+npm i -g auggy
 
 # Create an agent (interactive augment selection)
 auggy create zip
@@ -30,10 +30,23 @@ auggy create zip
 cp zip/.env.example zip/.env
 # Add your API key to zip/.env
 
-# Run it
+# Run locally (foreground)
 auggy dev zip
+
+# Or install as a launchd service (macOS, always-on)
+auggy start zip
+
+# Or deploy to the cloud (requires Railway CLI + `railway login`)
+auggy deploy zip --to railway
 ```
 
+The `auggy` binary requires [Bun](https://bun.sh) at runtime. The package
+ships TypeScript sources; Bun executes them directly without a build step.
+
+> Until the package is on npm, use the development install:
+> `git clone …augment-1 && cd augment-1 && bun install && bun link`.
+> The `auggy` binary lands on PATH the same way.
+
 ## How it works
 
 **Engines** drive the model call (one per agent). **Augments** plug in around it — context, tools, transport, memory (many per agent). Both are swappable via YAML.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auggy",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Modular agent runtime — composable augments, multi-engine, SQLite-first memory.",
   "keywords": [
     "agent",

package/src/augments/layered-memory/extractor/parse.ts

@@ -17,25 +17,83 @@ export type ParseResult =
   | { success: false; error: string };
 
 /**
- * Defensive JSON parser for the extraction LLM's response. The model
- * should emit a top-level JSON array of fact objects per `prompt.md`,
- * but real models occasionally drift (extra prose, missing fields,
- * type mismatches). This parser:
+ * Defensive JSON parser for the extraction LLM's response. The model should
+ * emit a top-level JSON array of fact objects per `prompt.md`, but real
+ * models drift (markdown code fences, leading/trailing prose, language tags,
+ * extra fields, type mismatches). This parser:
  *
- *   - Returns `{ success: false, error }` on any failure mode rather
- *     than throwing, so the auto-save handler can log and skip without
- *     killing the injected turn's tool-call execution.
- *   - Validates each entry's shape strictly: all five required fields
- *     must be present and the right primitive type. One bad entry
- *     fails the whole batch — partial writes would leave inconsistent
- *     storage, and the cost of a re-extraction is bounded.
- *   - Strips unknown keys to keep the storage schema clean across
- *     prompt-template revisions.
+ *   - Locates the JSON array via balanced-bracket extraction so wrappers
+ *     (Haiku's ```json fences, Sonnet's leading prose, etc) are tolerated
+ *     structurally — see `extractJsonArray` for the why.
+ *   - Returns `{ success: false, error }` on any failure mode rather than
+ *     throwing, so the auto-save handler can log and skip without killing
+ *     the injected turn's tool-call execution.
+ *   - Validates each entry's shape strictly: all five required fields must
+ *     be present and the right primitive type. One bad entry fails the
+ *     whole batch — partial writes would leave inconsistent storage and the
+ *     cost of a re-extraction is bounded.
+ *   - Strips unknown keys to keep the storage schema clean across prompt-
+ *     template revisions.
  */
+
+/**
+ * Locate and return the first top-level JSON array in the response, ignoring
+ * any wrapping (markdown code fences, leading prose, trailing prose, language
+ * tags, single-line vs multi-line layout, etc).
+ *
+ * Walks the raw string looking for the first `[`, then advances depth-tracking
+ * through nested arrays and objects, respecting JSON string boundaries and
+ * backslash escapes. Returns the substring `[..matching..]` or null when no
+ * balanced array is found.
+ *
+ * Why this approach: models wrap JSON output in different ways depending on
+ * the model, the prompt phrasing, and the moon's phase. Haiku 4.5 emits
+ * ```json\n[...]\n```; Sonnet sometimes leads with prose ("Here's the JSON:");
+ * Gemini occasionally appends "Hope this helps!". A regex tuned to one style
+ * breaks on the next variant. Balanced-bracket extraction is structurally
+ * robust — any wrapping the model adds is just text outside the array.
+ */
+function extractJsonArray(raw: string): string | null {
+  const start = raw.indexOf("[");
+  if (start === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < raw.length; i++) {
+    const c = raw[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString) {
+      if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      continue;
+    }
+    if (c === "[") depth++;
+    else if (c === "]") {
+      depth--;
+      if (depth === 0) return raw.slice(start, i + 1);
+    }
+  }
+
+  return null;
+}
+
 export function parseExtractionResponse(raw: string): ParseResult {
+  const jsonText = extractJsonArray(raw);
+  if (jsonText === null) {
+    return { success: false, error: "no balanced JSON array found in response" };
+  }
   let parsed: unknown;
   try {
-    parsed = JSON.parse(raw);
+    parsed = JSON.parse(jsonText);
   } catch (err) {
     return { success: false, error: `failed to parse JSON: ${(err as Error).message}` };
   }

package/src/cli/agent-index.ts

@@ -287,3 +287,47 @@ export function listAgents(opts: IndexOptions = {}): Array<IndexEntry & { name:
     ...entry,
   }));
 }
+
+/**
+ * Attach a cloud deployment record to a registered agent. Throws when the
+ * agent isn't registered — first call `addAgent`, then `setCloud`. Overwrites
+ * any prior cloud record (redeploy case).
+ *
+ * Holds the advisory lock for the read-modify-write window.
+ */
+export function setCloud(
+  name: string,
+  record: NonNullable<import("./types").CloudRecord>,
+  opts: IndexOptions = {},
+): void {
+  const lock = acquireLock(opts);
+  try {
+    const idx = readIndex(opts);
+    const entry = idx.agents[name];
+    if (!entry) {
+      throw new Error(`Agent "${name}" not registered — run \`auggy create ${name}\` first.`);
+    }
+    entry.cloud = record;
+    writeIndex(idx, opts);
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Clear an agent's cloud deployment record. Idempotent — no-op when already
+ * null. Does not throw when the agent isn't registered (matches removeAgent
+ * idempotency).
+ */
+export function clearCloud(name: string, opts: IndexOptions = {}): void {
+  const lock = acquireLock(opts);
+  try {
+    const idx = readIndex(opts);
+    const entry = idx.agents[name];
+    if (!entry) return;
+    entry.cloud = null;
+    writeIndex(idx, opts);
+  } finally {
+    lock.release();
+  }
+}

package/src/cli/commands/deploy.ts

@@ -0,0 +1,178 @@
+/**
+ * `auggy deploy <name> --to railway` command.
+ *
+ * Orchestrates the first-deploy + redeploy flows:
+ *
+ *   first-deploy: presence + auth checks → operator prompt for projectId →
+ *     stage bundle → write Dockerfile + entrypoint → link → addVolume →
+ *     generateDomain → push secrets (.env + AUGGY_PUBLIC_URL) → up →
+ *     capture status → write CloudRecord to index.
+ *
+ *   redeploy:    presence + auth checks → stage bundle → write Dockerfile +
+ *     entrypoint → link (idempotent) → re-push secrets → up → status →
+ *     update CloudRecord.deployedAt.
+ *
+ * Cleanly testable via a dependency-injected `RailwayCli` (real or mocked)
+ * plus pluggable prompt + logger helpers — no I/O hardcoded into the orchestrator.
+ *
+ * Per D7 (architecture deltas in the v1.0 plan): the URL is captured BEFORE
+ * `up` runs so AUGGY_PUBLIC_URL is set as a Railway env var, ensuring
+ * visitorAuth sees the publicUrl on first boot. This avoids a first-boot
+ * crash when agent.yaml interpolates `${AUGGY_PUBLIC_URL}` or similar.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgent, setCloud } from "../agent-index";
+import { stageBundle } from "../deploy/bundle";
+import { generateDockerfile, generateEntrypoint } from "../deploy/dockerfile";
+import type { RailwayCli } from "../deploy/railway-cli";
+import { loadSecretsPlan } from "../deploy/secrets";
+
+export interface DeployLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+export interface DeployOptions {
+  to: "railway";
+  yes: boolean;
+  auggyDir?: string;
+  cli: RailwayCli;
+  /** Prompt the operator for a Railway project ID. */
+  promptProjectId: () => Promise<string>;
+  /** Prompt the operator for yes/no confirmation. Receives a human-readable message. */
+  promptConfirm: (message: string) => Promise<boolean>;
+  logger: DeployLogger;
+}
+
+export interface DeployResult {
+  url: string;
+  projectId: string;
+  serviceId: string;
+  volumeId: string;
+}
+
+const VOLUME_MOUNT_PATH = "/app/data";
+
+export async function runDeploy(name: string, opts: DeployOptions): Promise<DeployResult> {
+  if (opts.to !== "railway") {
+    throw new Error(
+      `Only "railway" is supported in v1.0 (got "${opts.to}"). Other targets: deferred.`,
+    );
+  }
+
+  const entry = getAgent(name, { auggyDir: opts.auggyDir });
+  if (!entry) {
+    throw new Error(
+      `Agent "${name}" not registered. Run \`auggy create ${name}\` first, then \`auggy deploy ${name}\`.`,
+    );
+  }
+  const agentDir = entry.localDir;
+
+  // 1) Presence + auth checks (fail fast before any subprocess work).
+  await opts.cli.checkPresence();
+  await opts.cli.checkAuth();
+  opts.logger.info(`Railway CLI ready.`);
+
+  // 2) Determine first-deploy vs redeploy from existing CloudRecord.
+  const existingCloud = entry.cloud;
+  const isRedeploy = existingCloud !== null;
+
+  let projectId: string;
+  if (isRedeploy && existingCloud) {
+    projectId = existingCloud.projectId;
+    opts.logger.info(`Redeploying ${name} to Railway project ${projectId}.`);
+  } else {
+    projectId = await opts.promptProjectId();
+    opts.logger.info(`First deploy of ${name} to Railway project ${projectId}.`);
+  }
+
+  // 3) Stage the bundle (excludes secrets + volume-bound state).
+  const stagingDir = stageBundle({ agentDir, agentName: name });
+  opts.logger.info(`Bundle staged at ${stagingDir}.`);
+
+  // 4) Write Dockerfile + entrypoint into the staging dir.
+  writeFileSync(join(stagingDir, "Dockerfile"), generateDockerfile({ agentName: name }));
+  writeFileSync(join(stagingDir, "auggy-entrypoint.sh"), generateEntrypoint());
+
+  // 5) Load secrets plan and confirm with operator unless --yes.
+  const envPath = join(agentDir, ".env");
+  const plan = loadSecretsPlan(envPath);
+  if (plan.warnings.length > 0) {
+    for (const w of plan.warnings) opts.logger.warn(w);
+  }
+  if (!opts.yes) {
+    const summary =
+      plan.variables.length === 0
+        ? `No secrets to push (no .env file or all entries malformed).`
+        : `Push ${plan.variables.length} secret(s) to Railway:\n` +
+          plan.variables.map((v) => `  ${v.key} = ${v.redactedValue}`).join("\n");
+    const confirmed = await opts.promptConfirm(`${summary}\n\nProceed?`);
+    if (!confirmed) {
+      throw new Error("Deploy aborted by operator (declined secrets push).");
+    }
+  }
+
+  // 6) Link the staging dir to the Railway service. First deploy: Railway
+  //    auto-creates the service if --service name doesn't exist in the
+  //    project. Redeploy: idempotent — re-links the same service.
+  await opts.cli.link({ projectId, serviceName: name, cwd: stagingDir });
+  opts.logger.info(`Linked staging dir to project ${projectId}, service ${name}.`);
+
+  // 7) Volume: only add on first deploy. Redeploys keep the existing volume
+  //    (Railway preserves it via the volumeId in the existing CloudRecord).
+  if (!isRedeploy) {
+    await opts.cli.addVolume({
+      name: `${name}-data`,
+      mountPath: VOLUME_MOUNT_PATH,
+      cwd: stagingDir,
+    });
+    opts.logger.info(`Volume "${name}-data" mounted at ${VOLUME_MOUNT_PATH}.`);
+  }
+
+  // 8) Generate (or recover) the public domain. Idempotent: second call
+  //    returns the existing URL.
+  const url = await opts.cli.generateDomain({ cwd: stagingDir });
+  opts.logger.info(`Public URL: ${url}`);
+
+  // 9) Push secrets (.env keys + AUGGY_PUBLIC_URL). D7: AUGGY_PUBLIC_URL must
+  //    be set BEFORE `up` so visitorAuth sees the publicUrl on first boot.
+  for (const v of plan.variables) {
+    await opts.cli.setVariable({ key: v.key, value: v.value, cwd: stagingDir });
+  }
+  await opts.cli.setVariable({ key: "AUGGY_PUBLIC_URL", value: url, cwd: stagingDir });
+  opts.logger.info(`Pushed ${plan.variables.length + 1} env var(s) to Railway.`);
+
+  // 10) Trigger the build + deploy. --detach so we return without tailing
+  //     build logs; operator follows progress via Railway UI / `railway logs`.
+  await opts.cli.up({ cwd: stagingDir });
+  opts.logger.info(`Build queued.`);
+
+  // 11) Capture service metadata for the CloudRecord.
+  const status = await opts.cli.status({ cwd: stagingDir });
+  opts.logger.info(`Service status: ${status.deployment.status}.`);
+
+  // 12) Write CloudRecord to the agent index.
+  const result: DeployResult = {
+    url,
+    projectId,
+    serviceId: status.service.id,
+    volumeId: `${name}-data`,
+  };
+  setCloud(
+    name,
+    {
+      provider: "railway",
+      projectId: result.projectId,
+      serviceId: result.serviceId,
+      url: result.url,
+      volumeId: result.volumeId,
+      deployedAt: new Date().toISOString(),
+    },
+    { auggyDir: opts.auggyDir },
+  );
+
+  return result;
+}

package/src/cli/commands/remove.ts

@@ -5,10 +5,12 @@
  * --yes). Tolerates missing localDir (still cleans the index entry).
  */
 
-import { existsSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { confirm } from "@inquirer/prompts";
-import { getAgent, removeAgent } from "../agent-index";
+import { clearCloud, getAgent, removeAgent } from "../agent-index";
+import { createRailwayCli, type RailwayCli } from "../deploy/railway-cli";
 import { readPidManifest, isProcessAlive, removePidManifest } from "../pid-registry";
 
 function readConfigName(localDir: string): string | null {
@@ -26,8 +28,12 @@ function readConfigName(localDir: string): string | null {
 interface RemoveOptions {
   /** Skip the y/N prompt. */
   yes?: boolean;
+  /** When set with a cloud-deployed agent, also destroy the Railway service. */
+  cloud?: boolean;
   /** Override `~/.auggy/` for tests. */
   auggyDir?: string;
+  /** Inject a RailwayCli for tests (defaults to the real one). */
+  railwayCli?: RailwayCli;
 }
 
 export async function runRemove(name: string, opts: RemoveOptions = {}): Promise<void> {
@@ -88,6 +94,35 @@ export async function runRemove(name: string, opts: RemoveOptions = {}): Promise
   if (pidByCli) removePidManifest(name);
   if (pidByConfig && configName) removePidManifest(configName);
 
+  // --cloud: also destroy the Railway service before clearing the index.
+  // We do this AFTER local cleanup so a failed Railway call doesn't leave
+  // local state in an inconsistent half-deleted shape.
+  if (opts.cloud && entry.cloud) {
+    const cli = opts.railwayCli ?? createRailwayCli();
+    // `railway service delete` needs to be run from a dir linked to the
+    // service. Create a temp dir, link it, then delete.
+    const tmp = mkdtempSync(join(tmpdir(), `auggy-remove-${name}-`));
+    try {
+      await cli.link({
+        projectId: entry.cloud.projectId,
+        serviceName: name,
+        cwd: tmp,
+      });
+      await cli.destroyService({ cwd: tmp });
+      console.log(`Destroyed Railway service "${name}" (project ${entry.cloud.projectId}).`);
+    } catch (err) {
+      console.warn(
+        `warn: Railway service destruction failed: ${(err as Error).message}\n` +
+          `  Local cleanup proceeding; remove the Railway service manually if needed.`,
+      );
+    } finally {
+      try {
+        rmSync(tmp, { recursive: true, force: true });
+      } catch {}
+    }
+    clearCloud(name, { auggyDir: opts.auggyDir });
+  }
+
   // Clear index entry.
   removeAgent(name, { auggyDir: opts.auggyDir });
 

package/src/cli/deploy/bundle.ts

@@ -0,0 +1,64 @@
+/**
+ * Bundle staging — copies an agent dir into a fresh temp directory minus the
+ * exclusions defined by ADR-021 (`.env`, `workspace/`, `*.db*`, `node_modules/`,
+ * `.git/`, `.DS_Store`, `*.tmp`) plus this PR's additions (`.worktrees/`,
+ * `.claude/`).
+ *
+ * The deploy command runs `railway up` from the staging dir so volume-bound
+ * state (SQLite files) and secrets (`.env`) never enter the Railway image.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+interface StageBundleOptions {
+  agentDir: string;
+  agentName: string;
+}
+
+const EXCLUDED_NAMES = new Set([
+  ".env",
+  ".git",
+  ".DS_Store",
+  "node_modules",
+  "workspace",
+  ".worktrees",
+  ".claude",
+]);
+
+function isExcluded(name: string): boolean {
+  if (EXCLUDED_NAMES.has(name)) return true;
+  if (/\.db(-(?:wal|shm))?$/.test(name)) return true;
+  if (name.endsWith(".tmp")) return true;
+  return false;
+}
+
+function copyTree(src: string, dst: string): void {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (isExcluded(entry)) continue;
+    const srcPath = join(src, entry);
+    const dstPath = join(dst, entry);
+    const stats = statSync(srcPath);
+    if (stats.isDirectory()) {
+      copyTree(srcPath, dstPath);
+    } else if (stats.isFile()) {
+      copyFileSync(srcPath, dstPath);
+    }
+    // Skip symlinks/sockets/etc — agent dirs shouldn't have them.
+  }
+}
+
+/**
+ * Copy the agent dir into a fresh temp staging dir, minus exclusions.
+ * Returns the absolute path to the staging dir.
+ */
+export function stageBundle(opts: StageBundleOptions): string {
+  if (!existsSync(opts.agentDir)) {
+    throw new Error(`Agent directory not found: ${opts.agentDir}`);
+  }
+  const staging = mkdtempSync(join(tmpdir(), `auggy-deploy-${opts.agentName}-`));
+  copyTree(opts.agentDir, staging);
+  return staging;
+}

package/src/cli/deploy/dockerfile.ts

@@ -0,0 +1,89 @@
+/**
+ * Dockerfile + entrypoint generator for `auggy deploy`.
+ *
+ * The deploy command writes these strings into the staging dir before
+ * `railway up`. ADR-021 cloud design: bake-in the volume symlink dance +
+ * `auggy dev --internal-mode railway` invocation so `agent.yaml`'s
+ * `dbPath: ./<name>.db` paths work unchanged in cloud.
+ */
+
+const BUN_VERSION = "1.1-alpine";
+
+/**
+ * Known SQLite paths in the agent dir that need to live on the Railway
+ * volume across redeploys. Each is symlinked in the entrypoint script:
+ *
+ *   /app/<name>.db → /app/data/<name>.db   (volume target)
+ *
+ * The .db files do NOT exist at boot — they're created by SQLite on first
+ * attach, following the symlink. WAL/SHM sibling files are created
+ * alongside the resolved symlink target (i.e. on the volume).
+ *
+ * Drift risk (per plan §D2): if a new SQLite-backed augment ships with a
+ * non-listed path, its DB falls outside the volume and gets lost on
+ * redeploy. Update this list when new augments land. Today's eval suite
+ * catches data loss empirically via the cross-session-recall grader.
+ */
+const SQLITE_DB_NAMES = ["memory.db", "budgets.db", "visitor-auth.db", "link.db"];
+
+interface DockerfileOptions {
+  agentName: string;
+}
+
+export function generateDockerfile(opts: DockerfileOptions): string {
+  return `FROM oven/bun:${BUN_VERSION}
+
+WORKDIR /app
+
+# Install auggy globally so the entrypoint can call \`auggy dev\`.
+# (Phase 3 of the deploy plan: package will be published as @auggy/cli;
+# update this to "@auggy/cli" once published. Until then, build images
+# from a workspace clone.)
+RUN bun install -g auggy
+
+COPY . /app
+
+# Make the entrypoint executable.
+RUN chmod +x /app/auggy-entrypoint.sh
+
+# Railway mounts the persistent volume here.
+VOLUME ["/app/data"]
+
+# Railway routes traffic to the port declared by the app via PORT env.
+EXPOSE 8080
+
+ENTRYPOINT ["/app/auggy-entrypoint.sh", "${opts.agentName}"]
+`;
+}
+
+export function generateEntrypoint(): string {
+  const symlinks = SQLITE_DB_NAMES.map((name) => `ln -sf /app/data/${name} /app/${name}`).join(
+    "\n",
+  );
+
+  return `#!/bin/sh
+# Auggy Railway entrypoint.
+#
+# - The Railway volume is mounted at /app/data (persists across redeploys).
+# - SQLite-backed augments (layeredMemory, budgets, visitorAuth, link) write
+#   to ./<name>.db; we symlink each name into the volume so paths in
+#   agent.yaml stay unchanged between local and cloud.
+# - WAL/SHM siblings are created alongside the resolved symlink target by
+#   SQLite, i.e. they land on the volume.
+# - -f overwrites any prior symlink so redeploys don't fail on the second run.
+# - The .db files don't need to exist at boot — SQLite creates them on first
+#   attach, following the symlink to the volume.
+#
+# Drift risk: when a new SQLite-backed augment ships, add its .db name to the
+# SQLITE_DB_NAMES list in src/cli/deploy/dockerfile.ts.
+
+set -e
+
+mkdir -p /app/data
+
+${symlinks}
+
+# $1 is the agent name passed by ENTRYPOINT.
+exec auggy dev "$1" --internal-mode railway
+`;
+}

package/src/cli/deploy/railway-cli.ts

@@ -0,0 +1,190 @@
+/**
+ * Railway CLI subprocess wrapper.
+ *
+ * Sole owner of `railway` binary knowledge in the codebase. Every Railway
+ * operation calls `runRailway(args, opts)` which uses the injected spawn
+ * factory (defaults to `Bun.spawn`). Tests override the factory to mock
+ * subprocess behavior without spawning anything.
+ *
+ * Operator pre-requisites: `railway` CLI installed (https://docs.railway.com/develop/cli)
+ * and `railway login` completed. We trust the operator's auth context — same
+ * pattern as `git push` trusts `git`. No token storage in this codebase.
+ */
+
+export class RailwayCliMissingError extends Error {
+  constructor() {
+    super(
+      "Railway CLI not found. Install it: https://docs.railway.com/develop/cli, then `railway login`.",
+    );
+    this.name = "RailwayCliMissingError";
+  }
+}
+
+export class RailwayNotLoggedInError extends Error {
+  constructor(detail: string) {
+    super(`Railway CLI not authenticated: ${detail}\nRun \`railway login\` and try again.`);
+    this.name = "RailwayNotLoggedInError";
+  }
+}
+
+interface SpawnHandle {
+  exited: Promise<number>;
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+}
+
+export type RailwaySpawnFactory = (
+  cmd: string[],
+  opts?: { cwd?: string; env?: Record<string, string> },
+) => SpawnHandle;
+
+interface CreateRailwayCliOptions {
+  spawn?: RailwaySpawnFactory;
+}
+
+interface RunOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface RailwayStatus {
+  project: { id: string; name: string };
+  service: { id: string; name: string };
+  deployment: { status: string };
+}
+
+async function readAll(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) chunks.push(value);
+  }
+  const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    merged.set(c, offset);
+    offset += c.byteLength;
+  }
+  return new TextDecoder().decode(merged);
+}
+
+const defaultSpawn: RailwaySpawnFactory = (cmd, opts = {}) => {
+  const proc = Bun.spawn(cmd, {
+    cwd: opts.cwd,
+    env: opts.env ? { ...process.env, ...opts.env } : undefined,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    exited: proc.exited,
+    stdout: proc.stdout,
+    stderr: proc.stderr,
+  };
+};
+
+export interface RailwayCli {
+  checkPresence(): Promise<true>;
+  checkAuth(): Promise<string>;
+  link(args: { projectId: string; serviceName: string; cwd: string }): Promise<void>;
+  setVariable(args: { key: string; value: string; cwd: string }): Promise<void>;
+  up(args: { cwd: string }): Promise<void>;
+  generateDomain(args: { cwd: string }): Promise<string>;
+  addVolume(args: { name: string; mountPath: string; cwd: string }): Promise<void>;
+  status(args: { cwd: string }): Promise<RailwayStatus>;
+  destroyService(args: { cwd: string }): Promise<void>;
+}
+
+export function createRailwayCli(opts: CreateRailwayCliOptions = {}): RailwayCli {
+  const spawn = opts.spawn ?? defaultSpawn;
+
+  async function runRailway(
+    args: string[],
+    runOpts: RunOptions = {},
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    let handle: SpawnHandle;
+    try {
+      handle = spawn(["railway", ...args], runOpts);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new RailwayCliMissingError();
+      }
+      throw err;
+    }
+    const [stdout, stderr, exitCode] = await Promise.all([
+      readAll(handle.stdout),
+      readAll(handle.stderr),
+      handle.exited,
+    ]);
+    return { stdout, stderr, exitCode };
+  }
+
+  async function runOrThrow(
+    args: string[],
+    runOpts: RunOptions = {},
+  ): Promise<{ stdout: string; stderr: string }> {
+    const { stdout, stderr, exitCode } = await runRailway(args, runOpts);
+    if (exitCode !== 0) {
+      throw new Error(
+        `railway ${args.join(" ")} exited ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`,
+      );
+    }
+    return { stdout, stderr };
+  }
+
+  return {
+    async checkPresence() {
+      const { exitCode } = await runRailway(["--version"]);
+      if (exitCode !== 0) throw new RailwayCliMissingError();
+      return true;
+    },
+
+    async checkAuth() {
+      const { stdout, stderr, exitCode } = await runRailway(["whoami"]);
+      if (exitCode !== 0) {
+        throw new RailwayNotLoggedInError(stderr.trim() || "non-zero exit");
+      }
+      // Output forms observed: "Logged in as foo@example.com" or just "foo@example.com".
+      const match = stdout.match(/(?:Logged in as\s+)?([^\s]+@[^\s]+|\S+)$/m);
+      return match ? match[1]!.trim() : stdout.trim();
+    },
+
+    async link({ projectId, serviceName, cwd }) {
+      await runOrThrow(["link", "--project", projectId, "--service", serviceName], { cwd });
+    },
+
+    async setVariable({ key, value, cwd }) {
+      await runOrThrow(["variables", "--set", `${key}=${value}`], { cwd });
+    },
+
+    async up({ cwd }) {
+      await runOrThrow(["up", "--detach"], { cwd });
+    },
+
+    async generateDomain({ cwd }) {
+      // Idempotent: first call generates, second returns the existing URL.
+      const { stdout } = await runOrThrow(["domain", "--generate"], { cwd });
+      const match = stdout.match(/https:\/\/[a-z0-9.-]+/i);
+      if (!match) {
+        throw new Error(`railway domain --generate produced no URL: ${stdout.trim()}`);
+      }
+      return match[0];
+    },
+
+    async addVolume({ name, mountPath, cwd }) {
+      await runOrThrow(["volume", "add", name, "--mount-path", mountPath], { cwd });
+    },
+
+    async status({ cwd }) {
+      const { stdout } = await runOrThrow(["status", "--json"], { cwd });
+      const parsed = JSON.parse(stdout) as RailwayStatus;
+      return parsed;
+    },
+
+    async destroyService({ cwd }) {
+      await runOrThrow(["service", "delete", "--yes"], { cwd });
+    },
+  };
+}

package/src/cli/deploy/secrets.ts

@@ -0,0 +1,116 @@
+/**
+ * .env parser + Railway env-var push plan.
+ *
+ * Parses the agent dir's `.env` file (excluded from the bundle by design) and
+ * produces a structured plan the deploy command shows to the operator for
+ * confirmation BEFORE pushing to Railway. Plan structure:
+ *
+ *   { variables: [{ key, value, redactedValue }], warnings: [...] }
+ *
+ * `redactedValue` masks the middle of each value so the operator can confirm
+ * the right secret without the full key being printed to the terminal.
+ *
+ * This module does NOT call Railway. The deploy command calls `railway-cli`'s
+ * `setVariable` for each plan entry after operator confirmation.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+export interface EnvVariable {
+  key: string;
+  value: string;
+  redactedValue: string;
+}
+
+export interface SecretsPlan {
+  variables: EnvVariable[];
+  warnings: string[];
+}
+
+const KEY_RE = /^[A-Z_][A-Z0-9_]*$/i;
+
+function unquote(raw: string): string {
+  if (raw.length >= 2) {
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      return raw.slice(1, -1);
+    }
+  }
+  return raw;
+}
+
+/**
+ * Redact a secret for terminal display. Reveals the first 4 and last 4 chars
+ * for values >= 12 chars; shorter values are fully masked. Empty strings stay
+ * empty so the operator notices.
+ */
+export function redactValue(value: string): string {
+  if (value.length === 0) return "";
+  if (value.length < 12) return "*".repeat(value.length);
+  return `${value.slice(0, 4)}${"*".repeat(value.length - 8)}${value.slice(-4)}`;
+}
+
+/**
+ * Parse a `.env` file string into a SecretsPlan. Skips blank lines and
+ * comments. Tolerates quoted values + `export KEY=value` shorthand. Records
+ * a warning for any malformed line rather than throwing — operator gets the
+ * full picture before deciding to push.
+ */
+export function parseEnvText(text: string): SecretsPlan {
+  const variables: EnvVariable[] = [];
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]!;
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    const rest = line.startsWith("export ") ? line.slice("export ".length).trimStart() : line;
+    const eqIdx = rest.indexOf("=");
+    if (eqIdx < 0) {
+      warnings.push(`line ${i + 1}: no '=' found, skipped: "${line}"`);
+      continue;
+    }
+
+    const key = rest.slice(0, eqIdx).trim();
+    const value = unquote(rest.slice(eqIdx + 1).trim());
+
+    if (!KEY_RE.test(key)) {
+      warnings.push(`line ${i + 1}: invalid key "${key}", skipped`);
+      continue;
+    }
+
+    if (seen.has(key)) {
+      warnings.push(`line ${i + 1}: duplicate key "${key}" — later value overrides earlier`);
+    }
+    seen.add(key);
+
+    // Replace any prior entry for the same key.
+    const existing = variables.findIndex((v) => v.key === key);
+    const entry: EnvVariable = { key, value, redactedValue: redactValue(value) };
+    if (existing >= 0) {
+      variables[existing] = entry;
+    } else {
+      variables.push(entry);
+    }
+  }
+
+  return { variables, warnings };
+}
+
+/**
+ * Read the agent dir's `.env` file and return a SecretsPlan. Returns an empty
+ * plan + warning when `.env` doesn't exist (the agent may have no secrets,
+ * which is rare but allowed).
+ */
+export function loadSecretsPlan(envPath: string): SecretsPlan {
+  if (!existsSync(envPath)) {
+    return {
+      variables: [],
+      warnings: [`no .env file at ${envPath} — nothing to push to Railway`],
+    };
+  }
+  const text = readFileSync(envPath, "utf-8");
+  return parseEnvText(text);
+}

package/src/cli/index.ts

@@ -12,12 +12,14 @@
  *   auggy restart <name>             Stop + start
  *   auggy status [name]              Show running agents
  *   auggy ls                         List registered agents
- *   auggy remove <name> [--yes]      Delete an agent (dir + index entry)
+ *   auggy remove <name> [--yes] [--cloud]  Delete an agent (dir + index, optionally Railway service)
+ *   auggy deploy <name> --to railway       Deploy an agent to Railway
  *   auggy chat                       Launch local GUI
  *   auggy eval [name]                Run portable security eval suite
  */
 
 import { Command } from "commander";
+import pkg from "../../package.json" with { type: "json" };
 import { runCreate } from "./commands/create";
 import { runAdd } from "./commands/add";
 import { addSkillCommand } from "./commands/add-skill";
@@ -33,7 +35,7 @@ import { runLs } from "./commands/ls";
 
 const program = new Command();
 
-program.name("auggy").description("Auggy agent runtime CLI").version("0.1.0");
+program.name("auggy").description("Auggy agent runtime CLI").version(pkg.version);
 
 program
   .command("create <name>")
@@ -129,11 +131,14 @@ program
 
 program
   .command("remove <name>")
-  .description("Remove an agent (delete dir + clear index entry)")
+  .description(
+    "Remove an agent (delete dir + clear index entry; --cloud also destroys Railway service)",
+  )
   .option("--yes", "skip the confirmation prompt")
-  .action(async (name: string, opts: { yes?: boolean }) => {
+  .option("--cloud", "also destroy the agent's Railway service (when cloud-deployed)")
+  .action(async (name: string, opts: { yes?: boolean; cloud?: boolean }) => {
     try {
-      await runRemove(name, { yes: opts.yes });
+      await runRemove(name, { yes: opts.yes, cloud: opts.cloud });
     } catch (err) {
       console.error(`Error: ${(err as Error).message}`);
       process.exit(1);
@@ -172,6 +177,47 @@ program
     }
   });
 
+program
+  .command("deploy <name>")
+  .description("Deploy an agent to the cloud (--to railway)")
+  .option("--to <provider>", "deploy target (only `railway` supported in v1.0)", "railway")
+  .option("--yes", "skip the secrets-push confirmation prompt")
+  .action(async (name: string, opts: { to: string; yes?: boolean }) => {
+    try {
+      const { runDeploy } = await import("./commands/deploy");
+      const { createRailwayCli } = await import("./deploy/railway-cli");
+      const { input, confirm } = await import("@inquirer/prompts");
+
+      const cli = createRailwayCli();
+      const result = await runDeploy(name, {
+        to: opts.to as "railway",
+        yes: opts.yes ?? false,
+        cli,
+        promptProjectId: () =>
+          input({
+            message:
+              "Railway project ID (find it in the Railway dashboard URL or via `railway list`):",
+            validate: (v) => v.trim().length > 0 || "project ID required",
+          }),
+        promptConfirm: (message) => confirm({ message, default: false }),
+        logger: {
+          info: (msg) => console.log(msg),
+          warn: (msg) => console.warn(`warn: ${msg}`),
+          error: (msg) => console.error(`error: ${msg}`),
+        },
+      });
+      console.log(`\nDeployed ${name} to Railway.`);
+      console.log(`  URL:        ${result.url}`);
+      console.log(`  Project:    ${result.projectId}`);
+      console.log(`  Service:    ${result.serviceId}`);
+      console.log(`  Volume:     ${result.volumeId} (mounted at /app/data)`);
+      console.log(`\nFollow the build in the Railway dashboard or with \`railway logs\`.`);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
 program.addCommand(chatCommand());
 program.addCommand(evalCommand());