@devosurf/tesser 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -10,6 +10,7 @@ The interface both your agent and you drive everything through. Machine-first (A
 # auth & link (agent lane: set TESSER_TOKEN and skip all prompts)
 tesser login --instance URL --token tsk_…     # verify + store a profile
 tesser init <name>                            # scaffold a Project (one repo of automations)
+tesser upgrade                                # pin Tesser packages to this CLI version + refresh .tesser/docs
 tesser link [--repo URL]                      # register the Project on the instance
 tesser status                                 # instance health + deploy state
 
@@ -35,6 +36,8 @@ tesser logs <runId> [--follow]
 Auth resolution: `--token` > `TESSER_TOKEN` > profile (`~/.config/tesser/config.json`).
 Instance resolution: `--url` > `tesser.json` > `TESSER_URL` > profile > `http://localhost:8377`.
 
+`init` pins all Tesser packages to the CLI's exact version and writes committed agent reference docs under `.tesser/docs/` plus a user-editable `AGENTS.md`. During alpha/beta, upgrade with the target CLI version so package pins and docs move together: `npx @devosurf/tesser@<version> upgrade`.
+
 `tesser dev` spawns the separately-installed `tesser-server` binary (process boundary —
 this Apache package never links the AGPL server). `tesser test` runs the project's own
 test runner behind the scenes plus auto-smoke for untested automations; no third-party

package/dist/index.js

@@ -1,6 +1,6 @@
 // packages/cli/src/index.ts
 import { execFile as execFile2 } from "node:child_process";
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 import { promisify as promisify2 } from "node:util";
 import { Command } from "commander";
 
@@ -1171,8 +1171,429 @@ async function dev(out, projectRoot, project, opts) {
 }
 
 // packages/cli/src/commands/init.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join5 } from "node:path";
+
+// packages/cli/src/commands/project-docs.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join4 } from "node:path";
+var TESSER_DEPENDENCIES = ["@devosurf/tesser-sdk", "@devosurf/tesser-connectors"];
+var TESSER_DEV_DEPENDENCIES = ["@devosurf/tesser", "@devosurf/tesser-server", "@devosurf/tesser-testing"];
+var GENERATED_DOC_PATHS = [
+  ".tesser/docs/manifest.json",
+  ".tesser/docs/README.md",
+  ".tesser/docs/cli.md",
+  ".tesser/docs/sdk.md",
+  ".tesser/docs/connectors.md"
+];
+function projectPackageJson(name, version) {
+  return {
+    name,
+    private: true,
+    type: "module",
+    packageManager: "pnpm@9.12.0",
+    scripts: { test: "tesser test", deploy: "tesser deploy", dev: "tesser dev" },
+    dependencies: {
+      "@devosurf/tesser-sdk": version,
+      "@devosurf/tesser-connectors": version,
+      zod: "^4"
+    },
+    devDependencies: {
+      "@devosurf/tesser": version,
+      "@devosurf/tesser-server": version,
+      "@devosurf/tesser-testing": version,
+      vitest: "^4"
+    }
+  };
+}
+function writeProjectAgentInstructions(root, projectName, version, opts) {
+  const path = join4(root, "AGENTS.md");
+  if (!opts.overwrite && existsSync4(path)) return false;
+  writeFileSync2(path, projectAgentsMd(projectName, version));
+  return true;
+}
+function writeTesserGeneratedDocs(root, projectName, version) {
+  const docsDir = join4(root, ".tesser", "docs");
+  mkdirSync2(docsDir, { recursive: true });
+  const docs = {
+    "manifest.json": JSON.stringify(
+      {
+        kind: "tesser-agent-docs",
+        schemaVersion: 1,
+        generatedBy: "@devosurf/tesser",
+        tesserVersion: version,
+        project: projectName,
+        generatedFiles: GENERATED_DOC_PATHS.filter((path) => path !== ".tesser/docs/manifest.json")
+      },
+      null,
+      2
+    ) + "\n",
+    "README.md": docsReadmeMd(projectName, version),
+    "cli.md": cliReferenceMd(version),
+    "sdk.md": sdkReferenceMd(version),
+    "connectors.md": connectorsReferenceMd(version)
+  };
+  for (const [file, content] of Object.entries(docs)) {
+    writeFileSync2(join4(docsDir, file), content);
+  }
+  return [...GENERATED_DOC_PATHS];
+}
+function tesserGitignore() {
+  return `node_modules/
+.env
+
+# Tesser local runtime state from \`tesser dev\`; keep generated agent docs committed.
+.tesser/*
+!.tesser/
+!.tesser/docs/
+!.tesser/docs/**
+`;
+}
+function ensureTesserDocsGitignore(root) {
+  const path = join4(root, ".gitignore");
+  const block = `
+# Tesser local runtime state from \`tesser dev\`; keep generated agent docs committed.
+.tesser/*
+!.tesser/
+!.tesser/docs/
+!.tesser/docs/**
+`;
+  if (!existsSync4(path)) {
+    writeFileSync2(path, tesserGitignore());
+    return true;
+  }
+  const existing = readFileSync2(path, "utf8");
+  if (existing.includes("!.tesser/docs/**")) return false;
+  writeFileSync2(path, existing.replace(/\s*$/, "\n") + block);
+  return true;
+}
+function upgradeProject(out, project, version) {
+  const packagePath = join4(project.root, "package.json");
+  if (!existsSync4(packagePath)) {
+    throw new CliError(EXIT.USAGE, "not inside a package-backed Tesser project (missing package.json)");
+  }
+  const pkg = JSON.parse(readFileSync2(packagePath, "utf8"));
+  pinTesserPackages(pkg, version);
+  writeFileSync2(packagePath, JSON.stringify(pkg, null, 2) + "\n");
+  const docs = writeTesserGeneratedDocs(project.root, project.name, version);
+  const gitignoreUpdated = ensureTesserDocsGitignore(project.root);
+  const agentInstructionsCreated = writeProjectAgentInstructions(project.root, project.name, version, { overwrite: false });
+  const next = [
+    "pnpm install",
+    "tesser test --json",
+    'git add package.json pnpm-lock.yaml .gitignore AGENTS.md .tesser/docs && git commit -m "upgrade tesser"'
+  ];
+  out.data(
+    { upgraded: project.root, tesserVersion: version, docs, packageJson: "package.json", gitignoreUpdated, agentInstructionsCreated, next },
+    () => `upgraded ${project.root} to Tesser ${version}
+next:
+  pnpm install
+  tesser test --json
+  git add package.json pnpm-lock.yaml .gitignore AGENTS.md .tesser/docs && git commit -m "upgrade tesser"`
+  );
+}
+function pinTesserPackages(pkg, version) {
+  const dependencies = objectField(pkg, "dependencies");
+  for (const name of TESSER_DEPENDENCIES) dependencies[name] = version;
+  const devDependencies = objectField(pkg, "devDependencies");
+  for (const name of TESSER_DEV_DEPENDENCIES) devDependencies[name] = version;
+}
+function objectField(pkg, key) {
+  const existing = pkg[key];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) return existing;
+  const next = {};
+  pkg[key] = next;
+  return next;
+}
+function projectAgentsMd(projectName, version) {
+  return `# Working in this Tesser Project
+
+This repository is a Tesser **Project**: one git repo of automations deployed to a Tesser **Instance**.
+
+## Read first
+- [Generated Tesser reference](./.tesser/docs/README.md) \u2014 generated for Tesser ${version}.
+- [CLI reference](./.tesser/docs/cli.md) \u2014 use \`--json\` for machine-readable output.
+- [SDK reference](./.tesser/docs/sdk.md) \u2014 authoring pattern, \`ctx.step\`, tests.
+- [Connector reference](./.tesser/docs/connectors.md) \u2014 safe Connection and Secret usage.
+
+## Project rules
+- Use Tesser terms: **Automation**, **Trigger**, **Step**, **Project**, **Instance**, **Connector**, **Connection**, **Secret**, **Credential broker**, **Replay**.
+- One Automation per directory under \`automations/\`; colocate \`*.test.ts\` with each Automation.
+- Every side effect and external call must be inside \`ctx.step("stable-name", async () => ...)\`.
+- Declare credentials statically with \`connections: { ... }\` and \`secrets: { ... }\`; never read or print secret values.
+- Run \`pnpm install\` after init/upgrade, commit \`pnpm-lock.yaml\`, and never commit \`node_modules/\`.
+- Before deploy, run \`tesser test --json\` (and usually \`tesser build --json\`).
+- Deploy from git. Commit generated Tesser docs under \`.tesser/docs/\`; local runtime state in other \`.tesser/*\` paths stays ignored.
+
+## Upgrade rule
+To update this Project's pinned Tesser packages and generated references, run the target CLI version explicitly:
+
+\`\`\`bash
+npx @devosurf/tesser@<version> upgrade
+pnpm install
+tesser test --json
+\`\`\`
+
+Project name: \`${projectName}\`.
+`;
+}
+function docsReadmeMd(projectName, version) {
+  return `# Tesser agent reference
+
+Generated for Project \`${projectName}\` by \`@devosurf/tesser@${version}\`. Treat this directory as generated/vendor reference: do not hand-edit files under \`.tesser/docs/\`; customize local policy in \`AGENTS.md\`.
+
+## Start here
+1. Read \`AGENTS.md\` for project-specific policy.
+2. Use [cli.md](./cli.md) for command sequences and safe secret handling.
+3. Use [sdk.md](./sdk.md) before editing an Automation.
+4. Use [connectors.md](./connectors.md) before adding a Connection or Secret.
+
+## Version contract
+Tesser packages in \`package.json\` should be pinned exactly to \`${version}\`:
+
+- \`@devosurf/tesser\`
+- \`@devosurf/tesser-sdk\`
+- \`@devosurf/tesser-connectors\`
+- \`@devosurf/tesser-testing\`
+- \`@devosurf/tesser-server\`
+
+To upgrade, run the target CLI version so docs and packages move together:
+
+\`\`\`bash
+npx @devosurf/tesser@<version> upgrade
+pnpm install
+tesser test --json
+\`\`\`
+
+Commit \`package.json\`, \`pnpm-lock.yaml\`, \`.tesser/docs/\`, and any Automation/test changes together. Do not commit \`node_modules/\` or local runtime files such as \`.tesser/master.key\`.
+`;
+}
+function cliReferenceMd(version) {
+  return `# Tesser CLI reference
+
+Generated for \`@devosurf/tesser@${version}\`. The CLI is the agent interface: prefer \`--json\` when output will drive follow-up actions. stdout is data; stderr is logs/progress.
+
+## Install and invoke
+
+\`\`\`bash
+npm install -g @devosurf/tesser@${version}
+tesser --version
+
+# Or run an exact version without global install:
+npx @devosurf/tesser@${version} --version
+\`\`\`
+
+## Common flow
+
+\`\`\`bash
+tesser init my-project --instance https://tesser.example.com
+cd my-project
+pnpm install                    # creates pnpm-lock.yaml; commit it
+git init && git add -A && git commit -m init
+tesser login --instance https://tesser.example.com --token "$TESSER_TOKEN"
+tesser link --json              # registers this Project on the Instance
+tesser test --json
+tesser build --json
+tesser deploy --json
+\`\`\`
+
+## Commands agents commonly use
+
+- \`tesser init <name> [--dir DIR] [--instance URL]\` \u2014 scaffold a Project.
+- \`tesser upgrade\` \u2014 pin Tesser packages to this CLI version and refresh \`.tesser/docs/\`. To target a version: \`npx @devosurf/tesser@<version> upgrade\`.
+- \`tesser login --instance URL --token TOKEN\` \u2014 verify and store a profile. Prefer \`TESSER_TOKEN\` over pasting tokens into chat.
+- \`tesser link [--repo URL] --json\` \u2014 register the Project and print deploy-key/webhook setup data. CLI output must not include private keys or webhook secrets.
+- \`tesser status --json\` \u2014 instance health and deploy state.
+- \`tesser test [--smoke-only] [--automation ID] --json\` \u2014 fast local tests plus generated smoke tests.
+- \`tesser build --json\` \u2014 bundle and statically extract manifests. Use before deploy when changing requirements.
+- \`tesser dev [--port N] [--no-watch]\` \u2014 local Instance with embedded Postgres under ignored \`.tesser/*\` state.
+- \`tesser deploy [--ref REF] [--local] [--no-wait] --json\` \u2014 server-side build/test/promotion. Exit code 4 means halted on missing credentials; run \`tesser connect\`.
+- \`tesser connect [--wait] [--status TOKEN] --json\` \u2014 mint or poll the human connect link. The human supplies credentials in the browser; the agent only sees readiness.
+- \`tesser secrets list --json\`, \`tesser secrets rm <name> --json\`, \`printenv MY_SECRET | tesser secrets set <name> --value-stdin --json\`. Never put secret values in argv.
+- \`tesser runs list|show|trigger|signal|cancel --json\`; \`tesser logs <runId> [--follow]\`; \`tesser replay <runId>\`.
+- \`tesser rollback <automation> --to <version> --json\` \u2014 alias re-point; no rebuild.
+
+## Credential safety
+
+- Do not ask the user to paste secrets into chat. Use masked secret prompts where your harness supports them, or ask the human to run a command locally.
+- Never pass raw secret values as CLI arguments. Use environment variables, profiles, connect links, OAuth, or \`--value-stdin\`.
+- Treat connect links and status tokens as sensitive operational material.
+
+## Deploy hygiene
+
+- Run \`pnpm install\` after init/upgrade and commit \`pnpm-lock.yaml\`; the Instance installs from lockfiles for reproducible builds.
+- Do not commit \`node_modules/\`, \`.env\`, or local runtime state in \`.tesser/*\` outside \`.tesser/docs/\`.
+- Git is the source of truth. Commit and push before expecting a normal Instance deploy to see changes.
+`;
+}
+function sdkReferenceMd(version) {
+  return `# Tesser SDK reference
+
+Generated for \`@devosurf/tesser-sdk@${version}\`. Author ordinary async TypeScript; Tesser durability comes only from Steps.
+
+## Minimal Automation
+
+\`\`\`ts
+import { defineAutomation, onWebhook } from "@devosurf/tesser-sdk";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "hello",
+  trigger: onWebhook({ input: z.object({ name: z.string().default("world") }) }),
+  output: z.object({ greeting: z.string() }),
+
+  run: async (input, ctx) => {
+    const greeting = await ctx.step("compose", async () => \`hello, \${input.name}!\`);
+    return { greeting };
+  },
+});
+\`\`\`
+
+## Non-negotiable rules
+
+- Use **Step**, not node/task/action, for durable checkpoints.
+- Every side effect, external I/O call, Connector Action, bespoke HTTP request, file/network operation, or secret-dependent operation must happen inside \`ctx.step(name, fn)\`.
+- Step names are stable API for the journal. Use short, descriptive names such as \`fetch-customer\`, \`post-to-slack\`, \`charge-card\`.
+- Step outputs are journaled and must be serializable. Return plain data, not functions, class instances, streams, sockets, or live handles.
+- An Automation declares credentials statically at the top level. Do not hide requirements inside \`run\`.
+- Do not access provider tokens directly. Runtime-injected \`ctx.connections.*\` and \`ctx.secrets.*\` are the only runtime credential surfaces.
+
+## Triggers
+
+\`\`\`ts
+import { onWebhook, onSchedule, onEvent } from "@devosurf/tesser-sdk";
+
+const webhook = onWebhook({ input: schema, respond: "sync" });
+const schedule = onSchedule({ cron: "0 9 * * *", tz: "UTC" });
+const event = onEvent(myEvent);
+\`\`\`
+
+Connector triggers are reached from the Connector import, for example \`github.triggers.issueOpened({ repo: "owner/repo" })\` when supported.
+
+## Connections and Secrets
+
+\`\`\`ts
+import { defineAutomation, onWebhook, secret } from "@devosurf/tesser-sdk";
+import { slack } from "@devosurf/tesser-connectors";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "notify",
+  trigger: onWebhook({ input: z.object({ text: z.string() }) }),
+  connections: { slack },
+  secrets: { signingKey: secret({ describe: "Shared HMAC signing key" }) },
+  output: z.object({ ok: z.boolean() }),
+
+  run: async (input, ctx) => {
+    await ctx.step("post-message", () =>
+      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: input.text }),
+    );
+    return { ok: true };
+  },
+});
+\`\`\`
+
+Deploy halts if required Connections or Secrets are missing. The agent should surface the connect link to a human and poll status; it must not collect the secret value itself.
+
+## Tests
+
+Colocate tests beside each Automation.
+
+\`\`\`ts
+import { createTest } from "@devosurf/tesser-testing";
+import automation from "./index";
+
+test("greets by name", async () => {
+  const t = createTest({ automation });
+  const { result } = await t.run({ input: { name: "tesser" } });
+  expect(result).toEqual({ greeting: "hello, tesser!" });
+});
+\`\`\`
+
+For Connector calls, mock the Step result by Step name. Replay fixtures produced by \`tesser replay <runId>\` should become permanent regression tests.
+`;
+}
+function connectorsReferenceMd(version) {
+  return `# Tesser Connector reference
+
+Generated for \`@devosurf/tesser-connectors@${version}\`. A Connector is a typed integration; a Connection is an authed runtime instance injected by the Credential broker.
+
+## Available connector imports
+
+\`\`\`ts
+import {
+  anthropic,
+  claudeCode,
+  github,
+  gmail,
+  googleCalendar,
+  googleDocs,
+  googleDrive,
+  googleSheets,
+  http,
+  outlookMail,
+  pi,
+  resend,
+  slack,
+} from "@devosurf/tesser-connectors";
+\`\`\`
+
+Only import Connectors that the Automation declares in \`connections: { ... }\`.
+
+## Pattern
+
+\`\`\`ts
+import { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";
+import { github, slack } from "@devosurf/tesser-connectors";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "digest",
+  trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),
+  connections: { github, slack },
+  output: z.object({ posted: z.boolean(), count: z.number() }),
+
+  run: async (_input, ctx) => {
+    const issues = await ctx.step("fetch-open-issues", () =>
+      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),
+    );
+
+    if (issues.length === 0) return { posted: false, count: 0 };
+
+    await ctx.step("post-to-slack", () =>
+      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: \`\${issues.length} bugs\` }),
+    );
+
+    return { posted: true, count: issues.length };
+  },
+});
+\`\`\`
+
+## Common Actions
+
+- \`ctx.connections.http.get({ url, headers?, query? })\` and \`ctx.connections.http.request({ method, url, headers?, query?, body?, bodyText? })\`. Generic writes are not retry-safe; still wrap them in a Step.
+- \`ctx.connections.github.issues.list({ repo?, state?, labels?, limit? })\`, \`issues.create({ repo, title, body?, labels? })\`, \`issues.comment({ repo, number, body })\`, \`repos.get({ repo })\`.
+- \`ctx.connections.slack.chat.postMessage({ channel, text, threadTs? })\` and related Slack chat/conversation/user Actions.
+- \`ctx.connections.resend.emails.send(...)\`, Gmail/Outlook Mail and Google Calendar/Docs/Drive/Sheets Actions, Anthropic model Actions, Claude Code/Pi Harness-related Connectors: inspect package types or examples before using.
+
+## Connector triggers
+
+Some Connectors expose typed triggers, e.g. GitHub issue triggers, Slack event triggers, Gmail/Outlook mailbox poll triggers. Use the Connector's \`triggers\` constructors; do not hand-roll webhook delivery unless no Connector exists.
+
+\`\`\`ts
+trigger: github.triggers.issueOpened({ repo: "owner/repo" })
+\`\`\`
+
+## Safety rules
+
+- Connector Actions are not automatically durable. The Automation author must wrap every Action call in \`ctx.step\`.
+- The imported Connector is not a token-bearing client. The authed client exists only at \`ctx.connections.<name>\` inside \`run\`.
+- For bespoke APIs, combine \`http\` with declared \`secrets: { ... }\`; do not put API keys in source, tests, logs, CLI args, or committed env files.
+- If deploy halts on a missing Connection, surface \`tesser connect\` output to the human. The agent must not complete OAuth or paste raw secrets itself.
+`;
+}
+
+// packages/cli/src/commands/init.ts
 var EXAMPLE_AUTOMATION = `import { defineAutomation, onWebhook } from "@devosurf/tesser-sdk";
 import { z } from "zod";
 
@@ -1197,42 +1618,29 @@ test("greets by name", async () => {
   expect(result).toEqual({ greeting: "hello, tesser!" });
 });
 `;
-function init(out, name, opts) {
+function init(out, name, opts, version) {
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
     throw new CliError(EXIT.USAGE, "project name must be kebab-case");
   }
-  const root = join4(opts.dir ?? process.cwd(), name);
-  if (existsSync4(join4(root, "tesser.json"))) {
+  const root = join5(opts.dir ?? process.cwd(), name);
+  if (existsSync5(join5(root, "tesser.json"))) {
     throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
   }
-  mkdirSync2(join4(root, "automations", "hello"), { recursive: true });
-  writeFileSync2(
-    join4(root, "tesser.json"),
+  mkdirSync3(join5(root, "automations", "hello"), { recursive: true });
+  writeFileSync3(
+    join5(root, "tesser.json"),
     JSON.stringify({ project: name, ...opts.instance !== void 0 ? { instance: opts.instance } : {} }, null, 2) + "\n"
   );
-  writeFileSync2(
-    join4(root, "package.json"),
+  writeFileSync3(
+    join5(root, "package.json"),
     JSON.stringify(
-      {
-        name,
-        private: true,
-        type: "module",
-        packageManager: "pnpm@9.12.0",
-        scripts: { test: "tesser test", deploy: "tesser deploy", dev: "tesser dev" },
-        dependencies: { "@devosurf/tesser-sdk": "latest", "@devosurf/tesser-connectors": "latest", zod: "^4" },
-        devDependencies: {
-          "@devosurf/tesser": "latest",
-          "@devosurf/tesser-server": "latest",
-          "@devosurf/tesser-testing": "latest",
-          vitest: "^4"
-        }
-      },
+      projectPackageJson(name, version),
       null,
       2
     ) + "\n"
   );
-  writeFileSync2(
-    join4(root, "tsconfig.json"),
+  writeFileSync3(
+    join5(root, "tsconfig.json"),
     JSON.stringify(
       {
         compilerOptions: {
@@ -1249,41 +1657,50 @@ function init(out, name, opts) {
       2
     ) + "\n"
   );
-  writeFileSync2(
-    join4(root, "vitest.config.ts"),
+  writeFileSync3(
+    join5(root, "vitest.config.ts"),
     `import { defineConfig } from "vitest/config";
 export default defineConfig({ test: { globals: true, include: ["automations/**/*.test.ts"] } });
 `
   );
-  writeFileSync2(join4(root, ".gitignore"), "node_modules/\n.tesser/\n.env\n");
-  writeFileSync2(join4(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
-  writeFileSync2(join4(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
+  writeFileSync3(join5(root, ".gitignore"), tesserGitignore());
+  writeProjectAgentInstructions(root, name, version, { overwrite: true });
+  const docs = writeTesserGeneratedDocs(root, name, version);
+  writeFileSync3(join5(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
+  writeFileSync3(join5(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
+  const next = [
+    "cd " + name,
+    "pnpm install",
+    "git init && git add -A && git commit -m init",
+    "tesser link",
+    "tesser test"
+  ];
   out.data(
-    { created: root, next: ["cd " + name, "git init && git add -A && git commit -m init", "npm install (or pnpm)", "tesser link", "tesser test"] },
+    { created: root, tesserVersion: version, docs, next },
     () => `created ${root}
 next:
   cd ${name}
+  pnpm install       # creates pnpm-lock.yaml; commit it
   git init && git add -A && git commit -m init
-  pnpm install
-  tesser link    # register on your instance
-  tesser test    # green in milliseconds`
+  tesser link       # register on your instance
+  tesser test       # green in milliseconds`
   );
 }
 
 // packages/cli/src/commands/replay.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3, existsSync as existsSync5 } from "node:fs";
-import { join as join5 } from "node:path";
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4, existsSync as existsSync6 } from "node:fs";
+import { join as join6 } from "node:path";
 async function replay(out, api2, projectRoot, runId) {
   const { replay: run } = await api2.get(`/runs/${runId}/replay`);
-  const dir = join5(projectRoot, "automations", run.automation_id);
-  if (!existsSync5(dir)) {
+  const dir = join6(projectRoot, "automations", run.automation_id);
+  if (!existsSync6(dir)) {
     throw new CliError(EXIT.NOT_FOUND, `automation directory not found locally: automations/${run.automation_id}`);
   }
   const shortId = run.id.slice(0, 8);
-  const fixtureDir = join5(dir, "__replays__");
-  mkdirSync3(fixtureDir, { recursive: true });
-  const fixturePath = join5(fixtureDir, `${shortId}.replay.json`);
-  writeFileSync3(
+  const fixtureDir = join6(dir, "__replays__");
+  mkdirSync4(fixtureDir, { recursive: true });
+  const fixturePath = join6(fixtureDir, `${shortId}.replay.json`);
+  writeFileSync4(
     fixturePath,
     JSON.stringify(
       {
@@ -1300,8 +1717,8 @@ async function replay(out, api2, projectRoot, runId) {
       2
     ) + "\n"
   );
-  const testPath = join5(dir, `replay-${shortId}.test.ts`);
-  writeFileSync3(
+  const testPath = join6(dir, `replay-${shortId}.test.ts`);
+  writeFileSync4(
     testPath,
     `// Regression frozen from run ${run.id} (recorded status: ${run.status}).
 // Generated by \`tesser replay\` \u2014 adjust the final assertion once the bug is fixed.
@@ -1334,8 +1751,8 @@ run \`tesser test\` to execute it`
 
 // packages/cli/src/commands/test.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync6 } from "node:fs";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join7 } from "node:path";
 import { promisify } from "node:util";
 
 // packages/testing/src/engine.ts
@@ -1911,7 +2328,7 @@ async function smokeModelScripts(def) {
 }
 
 // packages/testing/src/cassette.ts
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync2, writeFileSync as writeFileSync4 } from "node:fs";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname3 } from "node:path";
 import { createHash } from "node:crypto";
 
@@ -1920,9 +2337,9 @@ var exec = promisify(execFile);
 function findVitest(projectRoot) {
   let dir = projectRoot;
   for (; ; ) {
-    const bin = join6(dir, "node_modules", ".bin", process.platform === "win32" ? "vitest.cmd" : "vitest");
-    if (existsSync6(bin)) return bin;
-    const parent = join6(dir, "..");
+    const bin = join7(dir, "node_modules", ".bin", process.platform === "win32" ? "vitest.cmd" : "vitest");
+    if (existsSync7(bin)) return bin;
+    const parent = join7(dir, "..");
     if (parent === dir) return null;
     dir = parent;
   }
@@ -1932,7 +2349,7 @@ async function runTests(out, projectRoot, opts) {
     (a) => opts.filter === void 0 || a.automationId === opts.filter
   );
   if (automations.length === 0) {
-    throw new CliError(EXIT.USAGE, `no automations found under ${join6(projectRoot, "automations")}`);
+    throw new CliError(EXIT.USAGE, `no automations found under ${join7(projectRoot, "automations")}`);
   }
   const report = {
     passed: true,
@@ -2022,7 +2439,7 @@ async function runTests(out, projectRoot, opts) {
 // packages/cli/src/index.ts
 var exec2 = promisify2(execFile2);
 var program = new Command();
-var VERSION = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8")).version;
+var VERSION = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version;
 function setup() {
   const opts = program.opts();
   return { out: new Output(opts.json ?? false), opts };
@@ -2049,7 +2466,15 @@ program.name("tesser").version(VERSION).description("Code-first, agent-native au
 program.command("init").argument("<name>", "project name (kebab-case)").option("--dir <dir>", "parent directory").option("--instance <url>", "instance URL to write into tesser.json").description("scaffold a new Project (one repo of automations)").action((name, cmdOpts) => {
   const { out } = setup();
   try {
-    init(out, name, cmdOpts);
+    init(out, name, cmdOpts, VERSION);
+  } catch (err) {
+    toExit(err, out);
+  }
+});
+program.command("upgrade").description("pin Tesser packages to this CLI version and refresh generated Project docs").action(() => {
+  const { out, opts } = setup();
+  try {
+    upgradeProject(out, requireProject(opts), VERSION);
   } catch (err) {
     toExit(err, out);
   }