create-mono-agent 0.12.0 → 0.14.0

package/README.md

@@ -1,8 +1,9 @@
 # create-mono-agent
 
-The unscoped npm-init installer for the mono-agent CLI. It ships two bins —
-`create-mono-agent` and `mono-agent` — each of which delegates every command to
-the CLI that lives in [`@mono-agent/agent-app`](https://www.npmjs.com/package/@mono-agent/agent-app).
+The unscoped npm-init entry point for mono-agent. Use it for a one-off guided
+setup with `npm create mono-agent@latest init`, or install it globally when you want
+the `mono-agent` command on `PATH`. Both shipped bins delegate to the CLI in
+[`@mono-agent/agent-app`](https://www.npmjs.com/package/@mono-agent/agent-app).
 
 Three equivalent entry points, one behaviour:
 
@@ -11,10 +12,12 @@ Three equivalent entry points, one behaviour:
 - `npm i -g create-mono-agent` — a global install that puts the natural `mono-agent` command on your `PATH`.
 
 On macOS, a one-off `npm create`/npx wizard may start the finished agent in the
-background. Before it does, `@mono-agent/agent-app` copies the exact executing
-package through npm into a private, verified runtime under
-`~/.mono-agent/runtimes/agent-app/`; launchd never keeps a disposable npm-cache
-path. This does not install a global command or mutate `PATH`.
+background. Before it does, `@mono-agent/agent-app` copies the already-resolved
+package closure it is executing into a private, verified runtime under
+`~/.mono-agent/runtimes/agent-app/`. That publication step never invokes npm or
+lifecycle scripts and never re-resolves dependencies; launchd therefore does
+not keep a disposable npm-cache path. It does not install a global command or
+mutate `PATH`.
 
 The bare `mono-agent` npm name is unavailable — npm rejects it as too similar to
 an unrelated `monoagent` package — so this installer follows the `create-*`
@@ -22,7 +25,14 @@ convention while still exposing the ergonomic `mono-agent` bin.
 
 ## Category
 
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
 Category: `app`
+Tier: `alias`
+Catalog responsibility: Unscoped npm-init installer (`npm create mono-agent`) shipping `create-mono-agent` and `mono-agent` bins that forward every command to @mono-agent/agent-app's CLI.
+
+<!-- package-metadata:end -->
 
 This is the catalog's sole `tier: "alias"` package: an unscoped publishable
 installer, not a core package with its own responsibility. It is excluded from the
@@ -38,8 +48,10 @@ work, and forward every invocation, unchanged, to `@mono-agent/agent-app`'s
 ## Install / Usage
 
 ```bash
-# One-off, no install (npm-init convention resolves create-mono-agent):
+# Recommended: one-off guided setup (npm resolves create-mono-agent):
 npm create mono-agent@latest init
+
+# The explicit npx form is equivalent:
 npx create-mono-agent init
 
 # Or install globally for the persistent `mono-agent` command:
@@ -57,8 +69,40 @@ child; see `delegateSignals`). This package adds nothing but the names. Prefer
 pinning the scoped host directly (`npm i -g @mono-agent/agent-app`) if you don't
 need the installer.
 
+## Architecture
+
+### Data flow
+
+Both bin names point to `dist/bin/mono-agent.js` and follow one path:
+
+1. `resolveAgentAppCliEntry()` resolves the installed
+   `@mono-agent/agent-app/package.json` and reads its declared `mono-agent` bin.
+2. The shim starts that exact CLI with the current Node executable, unchanged
+   arguments, and inherited standard input/output.
+3. `delegateSignals()` lets group-delivered Ctrl-C reach the child once,
+   forwards a targeted `SIGTERM`, and mirrors the child's exit code or signal.
+4. From that point, `@mono-agent/agent-app` owns all command behavior, including
+   any verified background-runtime publication.
+
+### Package structure
+
+| Module | Purpose |
+| --- | --- |
+| `src/bin/mono-agent.ts` | Shared entry point for both bin names. |
+| `src/resolve-agent-app-cli.ts` | Finds the dependency's declared CLI without hard-coding its build path. |
+| `src/delegate.ts` | Preserves signal and exit semantics while the real CLI runs. |
+
 ## Public API
 
+### Start here
+
+| Surface | Use |
+| --- | --- |
+| `npm create mono-agent@latest init` | One-off npm-init setup. |
+| `npx create-mono-agent init` | Explicit one-off setup. |
+| Global `mono-agent` bin | Persistent command after `npm i -g create-mono-agent`. |
+| Library imports | None; import programmatic APIs from `@mono-agent/agent-app`. |
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -82,6 +126,13 @@ command — all of that lives in `@mono-agent/agent-app`. It is metadata plus a
 delegating bin, nothing more. If the installer ever needs behaviour, that
 behaviour belongs in `@mono-agent/agent-app`, not here.
 
+## Related Documentation
+
+- [Create your first agent](https://mono-agent-docs.vercel.app/getting-started/quickstart/)
+- [CLI reference](https://mono-agent-docs.vercel.app/observability/cli-reference/)
+- [Agent folder layout](https://mono-agent-docs.vercel.app/config/folder-layout/)
+- [`@mono-agent/agent-app` package](https://github.com/robertsreberski/mono-agent/tree/main/packages/agent-app)
+
 ## Verification
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mono-agent",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "npm-init style installer for the mono-agent CLI: `npm create mono-agent`. Ships both a `create-mono-agent` and a `mono-agent` bin, each delegating to the @mono-agent/agent-app CLI.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -22,7 +22,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/agent-app": "0.12.0"
+    "@mono-agent/agent-app": "0.14.0"
   },
   "publishConfig": {
     "access": "public"