@ekanos/cli 0.1.5 → 0.1.7

package/README.md

@@ -23,9 +23,25 @@ npx @ekanos/cli dev
 | `logout` | Revoke the session at Auth0 and delete the local credentials. |
 | `whoami` | Print the identity the stored session authenticates as, plus a compact `seats` list (slug + roles) from the same endpoint `sources` uses — degrades to `seats: null` rather than failing if that lookup is unavailable. |
 | `status` | The read verb: login state for the resolved host, this project's `ekanos.json`, and its submissions on the host (`GET /api/partner/submissions`). Never fails just because you are logged out — it reports `authenticated: false` instead. |
-| `sources` | List every Fusion source you hold a developer or admin seat on (`GET /api/partner/sources`), with a marker on this project's current publish target. |
+| `sources` | List every Fusion source you hold a developer or source-admin seat on (`GET /api/partner/sources`), with a marker on this project's current publish target. |
 | `use` | `ekanos use <source-slug>` — set this project's publish target to a source you hold a seat on. Refuses (`forbidden`, with your actual seats in the hint) for a slug you don't hold a seat on, so a typo can't silently repoint a project. |
 | `publish` | Validate, pack and submit the integration to a Fusion host — refusing (`forbidden`) a target you hold no seat on, and confirming an ambiguous multi-seat target before submitting. See [Publish target verification](#publish-target-verification). |
+| `upgrade` | Move this toolchain to a coherent target version, with verify-and-rollback. `--check` reports current vs. target and changes nothing; a bare `upgrade` installs, verifies (`validate` + the test script), and rolls back automatically on any failure. See [Keeping the toolchain current](#keeping-the-toolchain-current). |
+
+### Installing: global is fine
+
+```bash
+npm i -g @ekanos/cli   # convenient — the `ekanos` binary is always on PATH
+```
+
+Inside a project, `validate`/`dev`/`publish`/`test` automatically delegate to
+**that project's own** pinned `@ekanos/cli` devDependency whenever it differs
+from the globally invoked binary — the same wrapper pattern as Gradle's
+`./gradlew` or `npx`. A partner with several integrations on different
+`@ekanos/sdk` versions gets the right toolchain per project without juggling
+installs by hand. Machine-level verbs (`init`, `login`, `logout`, `whoami`,
+`sources`, `use`, `status`, `upgrade`) never delegate — they always run on the
+binary you invoked. Set `EKANOS_NO_DELEGATE=1` to opt out for one invocation.
 
 ## Global flags
 
@@ -54,6 +70,13 @@ and `publish` itself in JSON/non-TTY mode or with an explicit `--source`, never
 prompts. `init` requires `--slug` and fails with a usage error naming the flag
 rather than asking for it.
 
+`validate`, `dev`, `publish` and `status` additionally carry an OPTIONAL
+`data.toolchain` field — `{ status: 'behind' | 'unsupported', current, target,
+upgradeCommand: 'ekanos upgrade' }` — whenever the background update check
+(see [Keeping the toolchain current](#keeping-the-toolchain-current)) finds
+this CLI is not current. Absent when current, unresolvable, or disabled via
+`EKANOS_NO_UPDATE_CHECK`.
+
 ### Exit codes (frozen public contract)
 
 `0` ok · `1` internal · `2` usage · `3` validation-findings · `4` auth-required ·
@@ -236,6 +259,62 @@ returns** rather than blocking on a dev server that never exits — the envelope
 `data.server` carries `{ started: false, command, url, port }` so the caller can
 start it itself. Pass `--start` to override.
 
+## Keeping the toolchain current
+
+Three independent defenses against a stale toolchain, all landing together
+because they're the same underlying problem seen from three angles:
+
+### The schema-skew gate
+
+`validate` and `publish` bundle an EXACT `@ekanos/integration-schema` version.
+If the PROJECT resolves a NEWER one (checked against both a direct install and
+whatever `@ekanos/sdk` itself declares a dependency on), both verbs fail fast
+with `precondition_failed` (exit 9) naming both versions — **before** loading
+the definition at all. This is not pedantry: in that state a field the newer
+schema added parses here as an `unrecognized_keys` zod issue, and the usual
+hint for that ("host-assigned fields are never partner-authorable — remove
+them") tells you to delete code that is completely correct. A real partner hit
+exactly this. Failing loudly beats answering falsely. The opposite skew — the
+project's schema is OLDER — only warns; the CLI's own validation is still
+correct, you just can't use fields it doesn't know about yet.
+
+### `ekanos upgrade`
+
+Resolves a COHERENT target version set — `GET /api/partner/toolchain` on your
+logged-in host when available, else the npm registry, with an explicit
+coherence check (the `@ekanos/sdk`/`@ekanos/ui`/`@ekanos/integration-schema`
+trio must share one version, and the sdk release at that version must pin
+exactly that schema) so a mid-publish registry state is refused rather than
+turned into an uninstallable tree.
+
+- `ekanos upgrade --check` — read-only, reports current vs. target, changes
+  nothing. Safe to run anytime, including from CI or an agent.
+- `ekanos upgrade` — snapshots `package.json` and the lockfile, installs the
+  target versions, then VERIFIES with `ekanos validate` and the project's own
+  test script. **Any failure at any step rolls everything back** — package.json,
+  lockfile and `node_modules` all restored — and reports exactly which step
+  failed with its output. `--yes` skips the interactive confirm (required
+  outside a real TTY); `--no-verify` skips the post-install verification.
+- On success, the agent-context files (`AGENTS.md`, `CLAUDE.md`, the Claude
+  Code skill) are regenerated from the newly installed CLI's templates —
+  byte-compared against what the PRE-upgrade CLI would have rendered, so a
+  file you haven't touched is refreshed and one you've edited is left alone
+  and reported as needing manual attention. A stale AGENTS.md teaches an agent
+  yesterday's contract, which is as harmful as a stale binary.
+
+### The proactive update notice
+
+`validate`, `dev`, `publish` and `status` all check (in the background, with a
+24h cache and a 1.5s timeout — never blocking, never changing a verb's exit
+code) whether a newer `@ekanos/cli` exists. Human mode gets one stderr line;
+JSON mode never prints prose to stdout, but the envelope's `data.toolchain`
+carries `{ status: 'behind' | 'unsupported', current, target, upgradeCommand
+}` when you're not current, and the same object rides the `claude-code-hint`
+stderr line so an agent can act on it without parsing prose. `unsupported`
+(below the host's declared minimum) makes `publish` fail fast — the host would
+reject the submission anyway. Set `EKANOS_NO_UPDATE_CHECK=1` to disable
+entirely.
+
 ## `ekanos init` on an existing project
 
 `npm init -y` first is fine. `init` **merges** into a `package.json` you
@@ -375,7 +454,7 @@ ekanos publish                 # verified before anything is packed or sent
 ```
 
 `ekanos sources` reads `GET /api/partner/sources` and lists every source you
-hold a `dev` or `admin` seat on, with a `*` marking the slug currently saved in
+hold a `developer` or `source_admin` seat on, with a `*` marking the slug currently saved in
 this project's `ekanos.json`. `ekanos use <slug>` persists that field, but only
 after confirming the slug names a source you actually hold a seat on — a typo
 or a stale slug is refused (`forbidden`) with your real seat list in the hint,

package/dist/bin.js

@@ -1,11 +1,24 @@
 #!/usr/bin/env node
+import { announceDelegation, delegate, planDelegation } from './delegate.js';
 import { run } from './index.js';
 /**
  * The bin entry — the ONLY place that calls process.exit, so `run()` stays a
  * pure, testable function that returns an exit code. Argv is sliced to drop
  * the node executable and this script path.
+ *
+ * Before dispatching, check whether this invocation should delegate to the
+ * current project's OWN pinned `@ekanos/cli` — see `delegate.ts` for why.
  */
-run(process.argv.slice(2))
+async function main() {
+    const argv = process.argv.slice(2);
+    const plan = planDelegation(argv, process.env, process.cwd());
+    if (plan.shouldDelegate) {
+        announceDelegation(plan, argv, process.env, process.stdout.isTTY === true);
+        return delegate(plan, argv, process.env);
+    }
+    return run(argv);
+}
+main()
     .then((code) => {
     process.exitCode = code;
 })

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACvB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;;IACxB,2EAA2E;IAC3E,oEAAoE;IACpE,uCAAuC;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCACE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,MAAA,KAAK,CAAC,KAAK,mCAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACxE,IAAI,CACL,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { run } from './index';\n\n/**\n * The bin entry — the ONLY place that calls process.exit, so `run()` stays a\n * pure, testable function that returns an exit code. Argv is sliced to drop\n * the node executable and this script path.\n */\nrun(process.argv.slice(2))\n  .then((code) => {\n    process.exitCode = code;\n  })\n  .catch((error: unknown) => {\n    // run() catches its own errors and emits the envelope; reaching here means\n    // the envelope machinery itself threw. Fail loudly on stderr (never\n    // stdout) with the internal exit code.\n    process.stderr.write(\n      `ekanos: fatal internal error: ${\n        error instanceof Error ? (error.stack ?? error.message) : String(error)\n      }\\n`,\n    );\n    process.exitCode = 1;\n  });\n"]}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B;;;;;;;GAOG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAE9D,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;QAC3E,OAAO,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED,IAAI,EAAE;KACH,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;;IACxB,2EAA2E;IAC3E,oEAAoE;IACpE,uCAAuC;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCACE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,MAAA,KAAK,CAAC,KAAK,mCAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACxE,IAAI,CACL,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { announceDelegation, delegate, planDelegation } from './delegate';\nimport { run } from './index';\n\n/**\n * The bin entry — the ONLY place that calls process.exit, so `run()` stays a\n * pure, testable function that returns an exit code. Argv is sliced to drop\n * the node executable and this script path.\n *\n * Before dispatching, check whether this invocation should delegate to the\n * current project's OWN pinned `@ekanos/cli` — see `delegate.ts` for why.\n */\nasync function main(): Promise<number> {\n  const argv = process.argv.slice(2);\n  const plan = planDelegation(argv, process.env, process.cwd());\n\n  if (plan.shouldDelegate) {\n    announceDelegation(plan, argv, process.env, process.stdout.isTTY === true);\n    return delegate(plan, argv, process.env);\n  }\n\n  return run(argv);\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code;\n  })\n  .catch((error: unknown) => {\n    // run() catches its own errors and emits the envelope; reaching here means\n    // the envelope machinery itself threw. Fail loudly on stderr (never\n    // stdout) with the internal exit code.\n    process.stderr.write(\n      `ekanos: fatal internal error: ${\n        error instanceof Error ? (error.stack ?? error.message) : String(error)\n      }\\n`,\n    );\n    process.exitCode = 1;\n  });\n"]}

package/dist/commands/dev.d.ts

@@ -7,6 +7,9 @@ export interface DevArgs {
     /**
      * Interface to bind. Defaults to loopback — see `resolveHost`. Anything
      * else is an explicit, warned-about decision to expose the harness.
+     *
+     * NOTE: unrelated to the Fusion HOST the update notice checks against —
+     * this is the local bind address for `next dev`, never a Fusion origin.
      */
     host?: string;
     /** Rewrite every generated file even when its bytes already match. */
@@ -17,6 +20,7 @@ export interface DevArgs {
      * a process that never exits.
      */
     start?: boolean;
+    env?: Record<string, string | undefined>;
 }
 /**
  * `dev` — scaffold the local harness shell into the partner's project, then

package/dist/commands/dev.js

@@ -5,6 +5,7 @@ import { preconditionError, usageError } from '../errors.js';
 import { HARNESS_DIR, HARNESS_PACKAGE, assertShellDirIsOurs, bootstrapHarnessConfig, ensureGitignoreEntry, missingDependencies, readInstalledHarness, scaffoldShell, } from '../harness-scaffold.js';
 import { detectPackageManager, execArgs, formatCommand, installCommand, } from '../package-manager.js';
 import { loadProject } from '../project.js';
+import { announceUpdate, checkForUpdate } from '../update-notice.js';
 const DEFAULT_PORT = 3100;
 /**
  * Loopback, NOT Next's default.
@@ -36,12 +37,14 @@ const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
  * and `.gitignore` never grows a duplicate line.
  */
 export async function runDev(ctx, args) {
-    var _a, _b;
+    var _a, _b, _c;
     const loaded = loadProject(args.dir);
     const port = parsePort(args.port);
     const host = parseHost(args.host);
     const exposed = !LOOPBACK_HOSTS.has(host);
     const pm = detectPackageManager(loaded.projectDir);
+    const notice = await checkForUpdate({ env: (_a = args.env) !== null && _a !== void 0 ? _a : process.env });
+    announceUpdate(ctx, notice);
     // Fail before writing anything: the shell declares no dependencies of its
     // own, so a missing one would otherwise surface as an opaque Next
     // resolution error minutes later.
@@ -98,24 +101,7 @@ export async function runDev(ctx, args) {
     const serverArgs = ['dev', '--port', String(port), '--hostname', host];
     const command = formatCommand(pm.bin, execArgs(pm, 'next', serverArgs));
     const url = `http://${displayHost(host)}:${port}`;
-    const scaffold = {
-        slug: loaded.primary.slug,
-        integrations: loaded.integrations.map((i) => i.slug),
-        projectDir: loaded.projectDir,
-        harnessDir: shell.harnessDir,
-        harnessVersion,
-        previousVersion: shell.previousVersion,
-        previousMarker: shell.previousMarker,
-        stale: shell.stale,
-        staleReasons: shell.staleReasons,
-        sourceGlobs: (_a = loaded.project.sourceGlobs) !== null && _a !== void 0 ? _a : [],
-        created: shell.created,
-        updated: shell.updated,
-        unchanged: shell.unchanged,
-        configBootstrapped: config.bootstrapped,
-        configPath: config.configPath,
-        gitignoreUpdated,
-    };
+    const scaffold = Object.assign({ slug: loaded.primary.slug, integrations: loaded.integrations.map((i) => i.slug), projectDir: loaded.projectDir, harnessDir: shell.harnessDir, harnessVersion, previousVersion: shell.previousVersion, previousMarker: shell.previousMarker, stale: shell.stale, staleReasons: shell.staleReasons, sourceGlobs: (_b = loaded.project.sourceGlobs) !== null && _b !== void 0 ? _b : [], created: shell.created, updated: shell.updated, unchanged: shell.unchanged, configBootstrapped: config.bootstrapped, configPath: config.configPath, gitignoreUpdated }, (notice ? { toolchain: notice } : {}));
     if (exposed) {
         ctx.warn(`WARNING: --host ${host} exposes the harness beyond this machine. It ` +
             'has no authentication, and it renders your fixtures and — in live ' +
@@ -126,7 +112,7 @@ export async function runDev(ctx, args) {
     // exits would hang its tool call forever and it would never see the
     // envelope, so JSON mode scaffolds and reports the command instead of
     // running it. `--start` overrides; `--no-start` opts out in a terminal.
-    const shouldStart = (_b = args.start) !== null && _b !== void 0 ? _b : !ctx.jsonMode;
+    const shouldStart = (_c = args.start) !== null && _c !== void 0 ? _c : !ctx.jsonMode;
     if (!shouldStart) {
         return ctx.succeed(Object.assign(Object.assign({}, scaffold), { server: { started: false, command, url, port, host, exposed } }), `dev: harness ready in ${shell.harnessDir}. Start it with: ${command}`);
     }

package/dist/commands/dev.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport * as path from 'node:path';\n\nimport { assertHarnessCompatible } from '../compatibility';\nimport type { CliContext } from '../context';\nimport { preconditionError, usageError } from '../errors';\nimport {\n  HARNESS_DIR,\n  HARNESS_PACKAGE,\n  assertShellDirIsOurs,\n  bootstrapHarnessConfig,\n  ensureGitignoreEntry,\n  missingDependencies,\n  readInstalledHarness,\n  scaffoldShell,\n} from '../harness-scaffold';\nimport {\n  detectPackageManager,\n  execArgs,\n  formatCommand,\n  installCommand,\n} from '../package-manager';\nimport { loadProject } from '../project';\n\nexport interface DevArgs {\n  /** Project directory (contains ekanos.json). Defaults to cwd. */\n  dir: string;\n  /** Port for the dev server. */\n  port?: string;\n  /**\n   * Interface to bind. Defaults to loopback — see `resolveHost`. Anything\n   * else is an explicit, warned-about decision to expose the harness.\n   */\n  host?: string;\n  /** Rewrite every generated file even when its bytes already match. */\n  force: boolean;\n  /**\n   * Explicit `--start` / `--no-start`. Undefined means \"decide from the\n   * output mode\": a JSON caller is an agent or a pipe and must not be handed\n   * a process that never exits.\n   */\n  start?: boolean;\n}\n\nconst DEFAULT_PORT = 3100;\n\n/**\n * Loopback, NOT Next's default.\n *\n * `next dev` binds 0.0.0.0 unless told otherwise, so the harness would be\n * reachable by anyone on the same network — a coffee-shop Wi-Fi, a shared\n * office VLAN — while we printed \"http://localhost:3100\" and implied\n * otherwise. It renders a partner's integration with their fixtures and, in\n * live mode, whatever their vendor API returns; there is no auth in front of\n * any of it. Binding loopback by default costs a partner nothing and makes\n * exposure a thing they ask for.\n */\nconst DEFAULT_HOST = '127.0.0.1';\n\n/** Addresses that are only reachable from this machine. */\nconst LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);\n\n/**\n * `dev` — scaffold the local harness shell into the partner's project, then\n * run it with their own Next.\n *\n * The shape of this verb follows from one rule: we must be able to ship a\n * harness bugfix as an `@ekanos/harness` version bump that a partner picks up\n * with `pnpm up`, with zero edits to any file they own. So everything under\n * `.ekanos/` is generated, gitignored and rewritten freely, `harness.config.ts`\n * at the project root is written once and never touched again, and all actual\n * harness behaviour lives in the installed package.\n *\n * Two idempotency properties matter and are both tested: a second run produces\n * byte-identical files and rewrites nothing (so Next's watcher stays quiet),\n * and `.gitignore` never grows a duplicate line.\n */\nexport async function runDev(ctx: CliContext, args: DevArgs): Promise<number> {\n  const loaded = loadProject(args.dir);\n  const port = parsePort(args.port);\n  const host = parseHost(args.host);\n  const exposed = !LOOPBACK_HOSTS.has(host);\n  const pm = detectPackageManager(loaded.projectDir);\n\n  // Fail before writing anything: the shell declares no dependencies of its\n  // own, so a missing one would otherwise surface as an opaque Next\n  // resolution error minutes later.\n  const missing = missingDependencies(loaded.projectDir);\n  if (missing.length > 0) {\n    throw preconditionError(\n      `${missing.length} package${missing.length === 1 ? '' : 's'} the ` +\n        `harness needs ${missing.length === 1 ? 'is' : 'are'} not installed ` +\n        `in ${loaded.projectDir}: ${missing.join(', ')}.`,\n      `Run \"${installCommand(pm, missing)}\" in ${loaded.projectDir}, then ` +\n        're-run \"ekanos dev\".',\n    );\n  }\n\n  const harness = readInstalledHarness(loaded.projectDir);\n  const harnessVersion = harness?.version;\n  if (!harnessVersion) {\n    throw preconditionError(\n      `${HARNESS_PACKAGE} is installed but declares no version.`,\n      `Reinstall it with \"${installCommand(pm, [HARNESS_PACKAGE])}\" in ` +\n        `${loaded.projectDir}, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  // The templates ship with the CLI and the code they import ships with the\n  // harness, so a partner can upgrade one without the other. Name that\n  // mismatch here rather than letting it surface later as a module-resolution\n  // error inside a shell we cheerfully certified as current.\n  assertHarnessCompatible({\n    harnessVersion,\n    harnessManifest: harness?.manifest,\n    installHint: (spec) => installCommand(pm, [spec]),\n  });\n\n  // Validate the shell target BEFORE writing anything at all. Bootstrapping\n  // harness.config.ts first and only then discovering that .ekanos/harness is\n  // a file or someone else's tree would leave the project half-scaffolded.\n  assertShellDirIsOurs(path.join(loaded.projectDir, HARNESS_DIR), args.force);\n\n  const config = bootstrapHarnessConfig(loaded.projectDir, loaded.integrations);\n  const shell = scaffoldShell({\n    projectDir: loaded.projectDir,\n    slug: loaded.primary.slug,\n    harnessVersion,\n    force: args.force,\n    sourceGlobs: loaded.project.sourceGlobs,\n  });\n  const gitignoreUpdated = ensureGitignoreEntry(loaded.projectDir);\n\n  if (shell.stale) {\n    ctx.log(\n      `Regenerating ${HARNESS_DIR} — ${shell.staleReasons.join('; ')}. ` +\n        `Nothing you own changed; ${config.configPath} is untouched.`,\n    );\n  }\n\n  if (config.bootstrapped) {\n    ctx.log(`  created harness.config.ts (yours — edit it, we never will)`);\n  }\n  for (const file of shell.created) ctx.log(`  created ${HARNESS_DIR}/${file}`);\n  for (const file of shell.updated) ctx.log(`  updated ${HARNESS_DIR}/${file}`);\n  if (gitignoreUpdated) ctx.log('  updated .gitignore (.ekanos/)');\n\n  // `--hostname` is passed ALWAYS, never left to Next's default, so the URL\n  // we print is the URL that is actually served.\n  const serverArgs = ['dev', '--port', String(port), '--hostname', host];\n  const command = formatCommand(pm.bin, execArgs(pm, 'next', serverArgs));\n  const url = `http://${displayHost(host)}:${port}`;\n\n  const scaffold = {\n    slug: loaded.primary.slug,\n    integrations: loaded.integrations.map((i) => i.slug),\n    projectDir: loaded.projectDir,\n    harnessDir: shell.harnessDir,\n    harnessVersion,\n    previousVersion: shell.previousVersion,\n    previousMarker: shell.previousMarker,\n    stale: shell.stale,\n    staleReasons: shell.staleReasons,\n    sourceGlobs: loaded.project.sourceGlobs ?? [],\n    created: shell.created,\n    updated: shell.updated,\n    unchanged: shell.unchanged,\n    configBootstrapped: config.bootstrapped,\n    configPath: config.configPath,\n    gitignoreUpdated,\n  };\n\n  if (exposed) {\n    ctx.warn(\n      `WARNING: --host ${host} exposes the harness beyond this machine. It ` +\n        'has no authentication, and it renders your fixtures and — in live ' +\n        'mode — real responses from your vendor API. Anyone who can reach ' +\n        `${url} can read all of it. Omit --host to bind ${DEFAULT_HOST}.`,\n    );\n  }\n\n  // A JSON caller is an agent or a pipe. Handing it a dev server that never\n  // exits would hang its tool call forever and it would never see the\n  // envelope, so JSON mode scaffolds and reports the command instead of\n  // running it. `--start` overrides; `--no-start` opts out in a terminal.\n  const shouldStart = args.start ?? !ctx.jsonMode;\n  if (!shouldStart) {\n    return ctx.succeed(\n      {\n        ...scaffold,\n        server: { started: false, command, url, port, host, exposed },\n      },\n      `dev: harness ready in ${shell.harnessDir}. Start it with: ${command}`,\n    );\n  }\n\n  ctx.log(`Starting the harness on ${url} (${command})…`);\n  const exitCode = await spawnServer({\n    ctx,\n    bin: pm.bin,\n    argv: execArgs(pm, 'next', serverArgs),\n    cwd: shell.harnessDir,\n  });\n\n  const data = {\n    ...scaffold,\n    server: { started: true, command, url, port, host, exposed, exitCode },\n  };\n\n  if (exitCode === 0) {\n    return ctx.succeed(data, `dev: harness stopped cleanly.`);\n  }\n\n  return ctx.failWith({\n    code: 'dev_server_failed',\n    message: `\"${command}\" exited with code ${exitCode}.`,\n    hint:\n      'Read the Next output on stderr. If it cannot resolve @ekanos/harness ' +\n      `or next, reinstall dependencies in ${loaded.projectDir}; if a route ` +\n      `fails to compile, delete ${shell.harnessDir} and re-run \"ekanos dev\".`,\n    // Transparent passthrough of Next's own exit code.\n    exitCode,\n    data,\n  });\n}\n\nfunction spawnServer(params: {\n  ctx: CliContext;\n  bin: string;\n  argv: string[];\n  cwd: string;\n}): Promise<number> {\n  return new Promise<number>((resolve, reject) => {\n    const child = spawn(params.bin, params.argv, {\n      cwd: params.cwd,\n      // stdin inherited so Next's own key handling works; stdout/stderr piped\n      // so we can route them and keep OUR stdout reserved for the envelope.\n      stdio: ['inherit', 'pipe', 'pipe'],\n    });\n\n    child.stdout?.on('data', (chunk: Buffer) => {\n      (params.ctx.jsonMode ? process.stderr : process.stdout).write(chunk);\n    });\n    child.stderr?.on('data', (chunk: Buffer) => {\n      process.stderr.write(chunk);\n    });\n\n    child.on('error', (error) => reject(error));\n    child.on('close', (code) => resolve(code ?? 1));\n  });\n}\n\n/**\n * The hostname to show a human. `127.0.0.1` is spelled `localhost` because\n * that is what people type; a wildcard bind is spelled `localhost` too, but\n * only after `exposed` has already been warned about — printing `0.0.0.0` as\n * a URL is not useful.\n */\nfunction displayHost(host: string): string {\n  if (host === '127.0.0.1' || host === '0.0.0.0' || host === '::') {\n    return 'localhost';\n  }\n  if (host === '::1') return '[::1]';\n  return host;\n}\n\nfunction parseHost(raw: string | undefined): string {\n  if (raw === undefined) return DEFAULT_HOST;\n\n  const host = raw.trim();\n  if (host.length === 0) {\n    throw usageError(\n      'Invalid --host \"\".',\n      `Pass an interface to bind, e.g. \"--host 0.0.0.0\" to expose the ` +\n        `harness on your network, or omit it to bind ${DEFAULT_HOST}.`,\n    );\n  }\n  return host;\n}\n\nfunction parsePort(raw: string | undefined): number {\n  if (raw === undefined) return DEFAULT_PORT;\n\n  const port = Number(raw);\n  if (!Number.isInteger(port) || port < 1 || port > 65535) {\n    throw usageError(\n      `Invalid --port \"${raw}\".`,\n      'Pass an integer between 1 and 65535, e.g. \"--port 3100\".',\n    );\n  }\n  return port;\n}\n"]}
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport * as path from 'node:path';\n\nimport { assertHarnessCompatible } from '../compatibility';\nimport type { CliContext } from '../context';\nimport { preconditionError, usageError } from '../errors';\nimport {\n  HARNESS_DIR,\n  HARNESS_PACKAGE,\n  assertShellDirIsOurs,\n  bootstrapHarnessConfig,\n  ensureGitignoreEntry,\n  missingDependencies,\n  readInstalledHarness,\n  scaffoldShell,\n} from '../harness-scaffold';\nimport {\n  detectPackageManager,\n  execArgs,\n  formatCommand,\n  installCommand,\n} from '../package-manager';\nimport { loadProject } from '../project';\nimport { announceUpdate, checkForUpdate } from '../update-notice';\n\nexport interface DevArgs {\n  /** Project directory (contains ekanos.json). Defaults to cwd. */\n  dir: string;\n  /** Port for the dev server. */\n  port?: string;\n  /**\n   * Interface to bind. Defaults to loopback — see `resolveHost`. Anything\n   * else is an explicit, warned-about decision to expose the harness.\n   *\n   * NOTE: unrelated to the Fusion HOST the update notice checks against —\n   * this is the local bind address for `next dev`, never a Fusion origin.\n   */\n  host?: string;\n  /** Rewrite every generated file even when its bytes already match. */\n  force: boolean;\n  /**\n   * Explicit `--start` / `--no-start`. Undefined means \"decide from the\n   * output mode\": a JSON caller is an agent or a pipe and must not be handed\n   * a process that never exits.\n   */\n  start?: boolean;\n  env?: Record<string, string | undefined>;\n}\n\nconst DEFAULT_PORT = 3100;\n\n/**\n * Loopback, NOT Next's default.\n *\n * `next dev` binds 0.0.0.0 unless told otherwise, so the harness would be\n * reachable by anyone on the same network — a coffee-shop Wi-Fi, a shared\n * office VLAN — while we printed \"http://localhost:3100\" and implied\n * otherwise. It renders a partner's integration with their fixtures and, in\n * live mode, whatever their vendor API returns; there is no auth in front of\n * any of it. Binding loopback by default costs a partner nothing and makes\n * exposure a thing they ask for.\n */\nconst DEFAULT_HOST = '127.0.0.1';\n\n/** Addresses that are only reachable from this machine. */\nconst LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);\n\n/**\n * `dev` — scaffold the local harness shell into the partner's project, then\n * run it with their own Next.\n *\n * The shape of this verb follows from one rule: we must be able to ship a\n * harness bugfix as an `@ekanos/harness` version bump that a partner picks up\n * with `pnpm up`, with zero edits to any file they own. So everything under\n * `.ekanos/` is generated, gitignored and rewritten freely, `harness.config.ts`\n * at the project root is written once and never touched again, and all actual\n * harness behaviour lives in the installed package.\n *\n * Two idempotency properties matter and are both tested: a second run produces\n * byte-identical files and rewrites nothing (so Next's watcher stays quiet),\n * and `.gitignore` never grows a duplicate line.\n */\nexport async function runDev(ctx: CliContext, args: DevArgs): Promise<number> {\n  const loaded = loadProject(args.dir);\n  const port = parsePort(args.port);\n  const host = parseHost(args.host);\n  const exposed = !LOOPBACK_HOSTS.has(host);\n  const pm = detectPackageManager(loaded.projectDir);\n\n  const notice = await checkForUpdate({ env: args.env ?? process.env });\n  announceUpdate(ctx, notice);\n\n  // Fail before writing anything: the shell declares no dependencies of its\n  // own, so a missing one would otherwise surface as an opaque Next\n  // resolution error minutes later.\n  const missing = missingDependencies(loaded.projectDir);\n  if (missing.length > 0) {\n    throw preconditionError(\n      `${missing.length} package${missing.length === 1 ? '' : 's'} the ` +\n        `harness needs ${missing.length === 1 ? 'is' : 'are'} not installed ` +\n        `in ${loaded.projectDir}: ${missing.join(', ')}.`,\n      `Run \"${installCommand(pm, missing)}\" in ${loaded.projectDir}, then ` +\n        're-run \"ekanos dev\".',\n    );\n  }\n\n  const harness = readInstalledHarness(loaded.projectDir);\n  const harnessVersion = harness?.version;\n  if (!harnessVersion) {\n    throw preconditionError(\n      `${HARNESS_PACKAGE} is installed but declares no version.`,\n      `Reinstall it with \"${installCommand(pm, [HARNESS_PACKAGE])}\" in ` +\n        `${loaded.projectDir}, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  // The templates ship with the CLI and the code they import ships with the\n  // harness, so a partner can upgrade one without the other. Name that\n  // mismatch here rather than letting it surface later as a module-resolution\n  // error inside a shell we cheerfully certified as current.\n  assertHarnessCompatible({\n    harnessVersion,\n    harnessManifest: harness?.manifest,\n    installHint: (spec) => installCommand(pm, [spec]),\n  });\n\n  // Validate the shell target BEFORE writing anything at all. Bootstrapping\n  // harness.config.ts first and only then discovering that .ekanos/harness is\n  // a file or someone else's tree would leave the project half-scaffolded.\n  assertShellDirIsOurs(path.join(loaded.projectDir, HARNESS_DIR), args.force);\n\n  const config = bootstrapHarnessConfig(loaded.projectDir, loaded.integrations);\n  const shell = scaffoldShell({\n    projectDir: loaded.projectDir,\n    slug: loaded.primary.slug,\n    harnessVersion,\n    force: args.force,\n    sourceGlobs: loaded.project.sourceGlobs,\n  });\n  const gitignoreUpdated = ensureGitignoreEntry(loaded.projectDir);\n\n  if (shell.stale) {\n    ctx.log(\n      `Regenerating ${HARNESS_DIR} — ${shell.staleReasons.join('; ')}. ` +\n        `Nothing you own changed; ${config.configPath} is untouched.`,\n    );\n  }\n\n  if (config.bootstrapped) {\n    ctx.log(`  created harness.config.ts (yours — edit it, we never will)`);\n  }\n  for (const file of shell.created) ctx.log(`  created ${HARNESS_DIR}/${file}`);\n  for (const file of shell.updated) ctx.log(`  updated ${HARNESS_DIR}/${file}`);\n  if (gitignoreUpdated) ctx.log('  updated .gitignore (.ekanos/)');\n\n  // `--hostname` is passed ALWAYS, never left to Next's default, so the URL\n  // we print is the URL that is actually served.\n  const serverArgs = ['dev', '--port', String(port), '--hostname', host];\n  const command = formatCommand(pm.bin, execArgs(pm, 'next', serverArgs));\n  const url = `http://${displayHost(host)}:${port}`;\n\n  const scaffold = {\n    slug: loaded.primary.slug,\n    integrations: loaded.integrations.map((i) => i.slug),\n    projectDir: loaded.projectDir,\n    harnessDir: shell.harnessDir,\n    harnessVersion,\n    previousVersion: shell.previousVersion,\n    previousMarker: shell.previousMarker,\n    stale: shell.stale,\n    staleReasons: shell.staleReasons,\n    sourceGlobs: loaded.project.sourceGlobs ?? [],\n    created: shell.created,\n    updated: shell.updated,\n    unchanged: shell.unchanged,\n    configBootstrapped: config.bootstrapped,\n    configPath: config.configPath,\n    gitignoreUpdated,\n    ...(notice ? { toolchain: notice } : {}),\n  };\n\n  if (exposed) {\n    ctx.warn(\n      `WARNING: --host ${host} exposes the harness beyond this machine. It ` +\n        'has no authentication, and it renders your fixtures and — in live ' +\n        'mode — real responses from your vendor API. Anyone who can reach ' +\n        `${url} can read all of it. Omit --host to bind ${DEFAULT_HOST}.`,\n    );\n  }\n\n  // A JSON caller is an agent or a pipe. Handing it a dev server that never\n  // exits would hang its tool call forever and it would never see the\n  // envelope, so JSON mode scaffolds and reports the command instead of\n  // running it. `--start` overrides; `--no-start` opts out in a terminal.\n  const shouldStart = args.start ?? !ctx.jsonMode;\n  if (!shouldStart) {\n    return ctx.succeed(\n      {\n        ...scaffold,\n        server: { started: false, command, url, port, host, exposed },\n      },\n      `dev: harness ready in ${shell.harnessDir}. Start it with: ${command}`,\n    );\n  }\n\n  ctx.log(`Starting the harness on ${url} (${command})…`);\n  const exitCode = await spawnServer({\n    ctx,\n    bin: pm.bin,\n    argv: execArgs(pm, 'next', serverArgs),\n    cwd: shell.harnessDir,\n  });\n\n  const data = {\n    ...scaffold,\n    server: { started: true, command, url, port, host, exposed, exitCode },\n  };\n\n  if (exitCode === 0) {\n    return ctx.succeed(data, `dev: harness stopped cleanly.`);\n  }\n\n  return ctx.failWith({\n    code: 'dev_server_failed',\n    message: `\"${command}\" exited with code ${exitCode}.`,\n    hint:\n      'Read the Next output on stderr. If it cannot resolve @ekanos/harness ' +\n      `or next, reinstall dependencies in ${loaded.projectDir}; if a route ` +\n      `fails to compile, delete ${shell.harnessDir} and re-run \"ekanos dev\".`,\n    // Transparent passthrough of Next's own exit code.\n    exitCode,\n    data,\n  });\n}\n\nfunction spawnServer(params: {\n  ctx: CliContext;\n  bin: string;\n  argv: string[];\n  cwd: string;\n}): Promise<number> {\n  return new Promise<number>((resolve, reject) => {\n    const child = spawn(params.bin, params.argv, {\n      cwd: params.cwd,\n      // stdin inherited so Next's own key handling works; stdout/stderr piped\n      // so we can route them and keep OUR stdout reserved for the envelope.\n      stdio: ['inherit', 'pipe', 'pipe'],\n    });\n\n    child.stdout?.on('data', (chunk: Buffer) => {\n      (params.ctx.jsonMode ? process.stderr : process.stdout).write(chunk);\n    });\n    child.stderr?.on('data', (chunk: Buffer) => {\n      process.stderr.write(chunk);\n    });\n\n    child.on('error', (error) => reject(error));\n    child.on('close', (code) => resolve(code ?? 1));\n  });\n}\n\n/**\n * The hostname to show a human. `127.0.0.1` is spelled `localhost` because\n * that is what people type; a wildcard bind is spelled `localhost` too, but\n * only after `exposed` has already been warned about — printing `0.0.0.0` as\n * a URL is not useful.\n */\nfunction displayHost(host: string): string {\n  if (host === '127.0.0.1' || host === '0.0.0.0' || host === '::') {\n    return 'localhost';\n  }\n  if (host === '::1') return '[::1]';\n  return host;\n}\n\nfunction parseHost(raw: string | undefined): string {\n  if (raw === undefined) return DEFAULT_HOST;\n\n  const host = raw.trim();\n  if (host.length === 0) {\n    throw usageError(\n      'Invalid --host \"\".',\n      `Pass an interface to bind, e.g. \"--host 0.0.0.0\" to expose the ` +\n        `harness on your network, or omit it to bind ${DEFAULT_HOST}.`,\n    );\n  }\n  return host;\n}\n\nfunction parsePort(raw: string | undefined): number {\n  if (raw === undefined) return DEFAULT_PORT;\n\n  const port = Number(raw);\n  if (!Number.isInteger(port) || port < 1 || port > 65535) {\n    throw usageError(\n      `Invalid --port \"${raw}\".`,\n      'Pass an integer between 1 and 65535, e.g. \"--port 3100\".',\n    );\n  }\n  return port;\n}\n"]}

package/dist/commands/init.d.ts

@@ -25,7 +25,53 @@ export interface InitArgs {
     force: boolean;
     /** Accepted for non-interactive ergonomics; init never prompts regardless. */
     yes: boolean;
+    /**
+     * Repeatable `--docs` entries — http(s) URLs or project-relative paths to
+     * the target API's documentation, written into the scaffolded ekanos.json
+     * as `docs`. Absent flag means the field is simply omitted; init never
+     * prompts for it.
+     */
+    docs?: string[];
 }
+/**
+ * The files init writes: template basename → destination path.
+ *
+ * `package.json` is handled separately (see `writeManifest`) because it is the
+ * one file a partner plausibly already has — `npm init -y` before `ekanos
+ * init` is the ordinary way to start — and skipping it silently costs them
+ * every dependency and script.
+ */
+/**
+ * The agent-context files. The SDK's day-1 users are coding agents, so the
+ * scaffold ships the authoring contract alongside the code: AGENTS.md is the
+ * contract, CLAUDE.md points at it, and the Claude Code skill teaches the
+ * iterate-validate-publish loop. Version-matched to the CLI because they live
+ * in its templates.
+ *
+ * Exported so `ekanos upgrade` can regenerate exactly this set from the
+ * NEWLY installed CLI's templates after a version bump — a stale AGENTS.md
+ * teaches an agent yesterday's contract, which is as harmful as a stale
+ * binary. One list, so `init` and `upgrade` can never disagree on what "the
+ * agent-context files" even are.
+ */
+export declare const AGENT_CONTEXT_FILES: {
+    template: string;
+    dest: string;
+}[];
+/**
+ * The docs-grounding artifacts, exported for the same reason as
+ * `AGENT_CONTEXT_FILES`: `upgrade` must create these when they are missing
+ * (an older project upgrading into a toolchain whose AGENTS.md and skills
+ * now reference them), and one list keeps `init` and `upgrade` from ever
+ * disagreeing on what they are. Unlike the agent-context files these are
+ * NEVER regenerated — `docs/api-notes.md` is agent/partner-authored after
+ * the scaffold and `.mcp.json` may carry local additions — only created
+ * when absent.
+ */
+export declare const DOCS_GROUNDING_FILES: {
+    template: string;
+    dest: string;
+}[];
 /**
  * `init` — instantiate a project from the bundled template: ekanos.json, a
  * working minimal defineIntegration, a test, a vitest config (with the
@@ -35,3 +81,18 @@ export interface InitArgs {
  * with a usage error naming the flag.
  */
 export declare function runInit(ctx: CliContext, args: InitArgs): ExitCode;
+/**
+ * Copy every bundled skill tree (`templates/skills/<name>/`) into the
+ * scaffolded project at `.claude/skills/<name>/`, verbatim — see
+ * `copyTreeVerbatim` for why these are bytes, never rendered templates. The
+ * walk is generic: a skill directory added to the published templates ships
+ * with no code change here. A CLI build with no `templates/skills/` at all
+ * (today's) scaffolds nothing and reports nothing.
+ *
+ * `skillsRoot` is injectable for tests; real callers take the default.
+ */
+export declare function copyBundledSkillTrees(targetDir: string, force: boolean, skillsRoot?: string, onRefusal?: 'throw' | 'collect'): {
+    created: string[];
+    skipped: SkippedFile[];
+    refused: string[];
+};

package/dist/commands/init.js

@@ -1,9 +1,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { printBanner } from '../banner.js';
-import { usageError } from '../errors.js';
+import { copyTreeVerbatim } from '../copy-tree.js';
+import { invalidStateError, usageError } from '../errors.js';
 import { mergeManifest, serializeManifest, } from '../merge-manifest.js';
-import { readTemplate, toDisplayName } from '../templates.js';
+import { docEntryProblem, serializeProject, } from '../project.js';
+import { classifyPath, readFileNoFollow, writeFileNoFollow } from '../safe-fs.js';
+import { readTemplate, templatesDir, toDisplayName } from '../templates.js';
 const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * The files init writes: template basename → destination path.
@@ -13,6 +16,42 @@ const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
  * init` is the ordinary way to start — and skipping it silently costs them
  * every dependency and script.
  */
+/**
+ * The agent-context files. The SDK's day-1 users are coding agents, so the
+ * scaffold ships the authoring contract alongside the code: AGENTS.md is the
+ * contract, CLAUDE.md points at it, and the Claude Code skill teaches the
+ * iterate-validate-publish loop. Version-matched to the CLI because they live
+ * in its templates.
+ *
+ * Exported so `ekanos upgrade` can regenerate exactly this set from the
+ * NEWLY installed CLI's templates after a version bump — a stale AGENTS.md
+ * teaches an agent yesterday's contract, which is as harmful as a stale
+ * binary. One list, so `init` and `upgrade` can never disagree on what "the
+ * agent-context files" even are.
+ */
+export const AGENT_CONTEXT_FILES = [
+    { template: 'AGENTS.md.tmpl', dest: 'AGENTS.md' },
+    { template: 'CLAUDE.md.tmpl', dest: 'CLAUDE.md' },
+    { template: 'claude-skill.md.tmpl', dest: '.claude/skills/ekanos/SKILL.md' },
+];
+/**
+ * The docs-grounding artifacts, exported for the same reason as
+ * `AGENT_CONTEXT_FILES`: `upgrade` must create these when they are missing
+ * (an older project upgrading into a toolchain whose AGENTS.md and skills
+ * now reference them), and one list keeps `init` and `upgrade` from ever
+ * disagreeing on what they are. Unlike the agent-context files these are
+ * NEVER regenerated — `docs/api-notes.md` is agent/partner-authored after
+ * the scaffold and `.mcp.json` may carry local additions — only created
+ * when absent.
+ */
+export const DOCS_GROUNDING_FILES = [
+    // The agent-authored snapshot of the target API — see the template itself
+    // and AGENTS.md's "API documentation" section for the convention.
+    { template: 'docs/api-notes.md.tmpl', dest: 'docs/api-notes.md' },
+    // Per-project MCP config so Claude Code picks up Context7 (the docs
+    // fallback in the resolution ladder) without any global setup.
+    { template: 'mcp.json.tmpl', dest: '.mcp.json' },
+];
 const FILES = [
     { template: 'ekanos.json.tmpl', dest: 'ekanos.json' },
     { template: 'gitignore.tmpl', dest: '.gitignore' },
@@ -25,14 +64,8 @@ const FILES = [
         template: 'src/integration.test.ts.tmpl',
         dest: 'src/integration.test.ts',
     },
-    // The agent-context files. The SDK's day-1 users are coding agents, so the
-    // scaffold ships the authoring contract alongside the code: AGENTS.md is
-    // the contract, CLAUDE.md points at it, and the Claude Code skill teaches
-    // the iterate-validate-publish loop. Version-matched to the CLI because
-    // they live in its templates.
-    { template: 'AGENTS.md.tmpl', dest: 'AGENTS.md' },
-    { template: 'CLAUDE.md.tmpl', dest: 'CLAUDE.md' },
-    { template: 'claude-skill.md.tmpl', dest: '.claude/skills/ekanos/SKILL.md' },
+    ...DOCS_GROUNDING_FILES,
+    ...AGENT_CONTEXT_FILES,
 ];
 /**
  * `init` — instantiate a project from the bundled template: ekanos.json, a
@@ -43,6 +76,7 @@ const FILES = [
  * with a usage error naming the flag.
  */
 export function runInit(ctx, args) {
+    var _a;
     const slug = args.slug;
     if (!slug) {
         throw usageError('init requires a slug.', 'Pass it explicitly: "ekanos init --slug <your-integration> --yes". ' +
@@ -52,6 +86,18 @@ export function runInit(ctx, args) {
         throw usageError(`Invalid slug "${slug}".`, 'Use kebab-case: lowercase [a-z0-9] segments joined by single hyphens, ' +
             'e.g. "acme-crm".');
     }
+    // Same rule the ekanos.json schema enforces, applied at the flag so a bad
+    // entry fails HERE (usage, exit 2) instead of scaffolding a project whose
+    // very first `ekanos validate` cannot even load its config.
+    const docs = (_a = args.docs) !== null && _a !== void 0 ? _a : [];
+    for (const entry of docs) {
+        const problem = docEntryProblem(entry);
+        if (problem) {
+            throw usageError(`Invalid --docs value: ${problem}`, 'Pass --docs an http(s) URL or a project-relative path, e.g. ' +
+                '"--docs https://developer.example.com/openapi.json" or ' +
+                '"--docs docs/api.md". Repeat the flag for multiple entries.');
+        }
+    }
     // Default to `./<slug>`, not the cwd: scaffolding six files into whatever
     // directory the partner happened to be sitting in is how a real project got
     // polluted. `--dir .` remains the explicit way to scaffold in place.
@@ -61,9 +107,34 @@ export function runInit(ctx, args) {
     const vars = { SLUG: slug, DISPLAY_NAME: toDisplayName(slug) };
     const created = [];
     const skipped = [];
+    // The project root is the guard for every write below: creating it raw is
+    // fine (it is the boundary, not inside it), but everything under it goes
+    // through safe-fs so a planted symlink refuses loudly instead of teleporting
+    // a write outside the project. See safe-fs.ts for the threat model. The one
+    // case the guard cannot see is the boundary ITSELF being a symlink — the
+    // containment math is lexical against `targetDir`, so a planted link there
+    // would relocate every "contained" write wholesale. Refuse it. (A symlinked
+    // ANCESTOR — macOS's /tmp, a linked home — stays fine: only the leaf is
+    // checked.)
+    let targetStats = null;
+    try {
+        targetStats = fs.lstatSync(targetDir);
+    }
+    catch (_b) {
+        targetStats = null; // does not exist yet — ours to create
+    }
+    if (targetStats === null || targetStats === void 0 ? void 0 : targetStats.isSymbolicLink()) {
+        throw invalidStateError(`The target directory ${targetDir} is a symlink, so the scaffold's ` +
+            'write-containment guarantees cannot hold there.', 'Scaffold into the real directory (pass its resolved path to --dir), ' +
+            'or remove the symlink first.');
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
     for (const { template, dest } of FILES) {
         const destPath = path.join(targetDir, dest);
-        if (fs.existsSync(destPath) && !args.force) {
+        const kind = classifyPath(destPath);
+        // A symlink is never "already exists": skipping would keep the plant, and
+        // writing through it is the attack — writeFileNoFollow refuses it.
+        if (kind !== 'missing' && kind !== 'symlink' && !args.force) {
             skipped.push({
                 file: dest,
                 reason: 'it already exists',
@@ -72,10 +143,14 @@ export function runInit(ctx, args) {
             });
             continue;
         }
-        fs.mkdirSync(path.dirname(destPath), { recursive: true });
-        fs.writeFileSync(destPath, readTemplate(template, vars));
+        writeFileNoFollow(targetDir, destPath, dest === 'ekanos.json'
+            ? renderEkanosConfig(vars, docs)
+            : readTemplate(template, vars));
         created.push(dest);
     }
+    const skills = copyBundledSkillTrees(targetDir, args.force);
+    created.push(...skills.created);
+    skipped.push(...skills.skipped);
     const manifest = writeManifest(targetDir, vars, args.force);
     if (manifest.kind === 'created')
         created.push('package.json');
@@ -117,6 +192,56 @@ export function runInit(ctx, args) {
     printBanner(ctx, 'full');
     return ctx.succeed(data, summary);
 }
+/**
+ * The scaffolded ekanos.json: the template, plus the collected `--docs`
+ * entries when there are any. Parse-then-serialize (rather than string
+ * surgery) so the written file is exactly what `loadProject` will read back.
+ */
+function renderEkanosConfig(vars, docs) {
+    const rendered = readTemplate('ekanos.json.tmpl', vars);
+    if (docs.length === 0)
+        return rendered;
+    const project = JSON.parse(rendered);
+    return serializeProject(Object.assign(Object.assign({}, project), { docs }));
+}
+/**
+ * Copy every bundled skill tree (`templates/skills/<name>/`) into the
+ * scaffolded project at `.claude/skills/<name>/`, verbatim — see
+ * `copyTreeVerbatim` for why these are bytes, never rendered templates. The
+ * walk is generic: a skill directory added to the published templates ships
+ * with no code change here. A CLI build with no `templates/skills/` at all
+ * (today's) scaffolds nothing and reports nothing.
+ *
+ * `skillsRoot` is injectable for tests; real callers take the default.
+ */
+export function copyBundledSkillTrees(targetDir, force, skillsRoot = path.join(templatesDir(), 'skills'), onRefusal = 'throw') {
+    if (!fs.existsSync(skillsRoot))
+        return { created: [], skipped: [], refused: [] };
+    const created = [];
+    const skipped = [];
+    const refused = [];
+    const skillDirs = fs
+        .readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const name of skillDirs) {
+        const destBase = path.join('.claude', 'skills', name);
+        const result = copyTreeVerbatim(path.join(skillsRoot, name), path.join(targetDir, destBase), { force, root: targetDir, onRefusal });
+        created.push(...result.created.map((rel) => path.join(destBase, rel)));
+        refused.push(...result.refused.map((rel) => path.join(destBase, rel)));
+        skipped.push(...result.skipped.map((rel) => {
+            const file = path.join(destBase, rel);
+            return {
+                file,
+                reason: 'it already exists',
+                hint: `Compare it against the bundled skill and merge anything you ` +
+                    `are missing, or re-run with --force to overwrite ${file}.`,
+            };
+        }));
+    }
+    return { created, skipped, refused };
+}
 /**
  * Write or MERGE package.json.
  *
@@ -129,15 +254,17 @@ export function runInit(ctx, args) {
 function writeManifest(targetDir, vars, force) {
     const destPath = path.join(targetDir, 'package.json');
     const rendered = readTemplate('package.json.tmpl', vars);
-    if (!fs.existsSync(destPath) || force) {
-        fs.mkdirSync(path.dirname(destPath), { recursive: true });
-        fs.writeFileSync(destPath, rendered);
+    // readFileNoFollow refuses a symlinked package.json outright, so the write
+    // below can never follow one either; null means genuinely absent.
+    const existingRaw = readFileNoFollow(targetDir, destPath);
+    if (existingRaw === null || force) {
+        writeFileNoFollow(targetDir, destPath, rendered);
         return { kind: 'created', added: [], kept: [], notes: [] };
     }
     const template = JSON.parse(rendered);
     let existing;
     try {
-        existing = JSON.parse(fs.readFileSync(destPath, 'utf8'));
+        existing = JSON.parse(existingRaw);
     }
     catch (error) {
         // Unparseable: do not guess, and do not clobber. Name the fix.
@@ -164,7 +291,7 @@ function writeManifest(targetDir, vars, force) {
             notes: result.notes,
         };
     }
-    fs.writeFileSync(destPath, serializeManifest(result.manifest));
+    writeFileNoFollow(targetDir, destPath, serializeManifest(result.manifest));
     return {
         kind: 'merged',
         added: result.added,