@phreshos/cli 0.1.17 → 0.1.19

package/README.md

@@ -399,10 +399,10 @@ are the canonical locations the package just created. An explicit
 and means `true`. At least one declared half must resolve to true.
 
 There is **no wrapping directory**: `program.json`, `server/`, `client/`,
-and optional `icon.png` sit at the package's root, and the system names the
-directory it installs into from your program's `identity`. Service API
-documentation belongs to the live service that exposes it and is therefore
-not part of the Program package.
+optional `icon.png`, and optional `agent.md` sit at the package's root. The
+system names the directory it installs into from your program's `identity`.
+An authored agent document may use any project-relative path, while packaging
+normalizes it to `agent.md`.
 
 Nothing about the system moves because this exists. `program.json` is
 still the only thing the system reads, and a package assembled by hand

package/dist/derive.js

@@ -30,6 +30,7 @@ export default function derive(config, directory, which) {
         // Where it already is. Unlike pack, which gives it its canonical
         // name, this points into the authoring tree and leaves it alone.
         icon: config.icon && resolve(directory, config.icon),
+        agent: config.agent && resolve(directory, config.agent),
         // Beside the source, and said out loud. A program built from an
         // object resolves what it leaves unsaid against the *system's*
         // working directory — so silence here means a program keeps what

package/dist/pack.js

@@ -18,7 +18,8 @@ import build from "./build-command.js";
  * a declared half always has a location, even when the system chose it.
  *
  * There is **no wrapping directory**. `program.json`, `server/`,
- * `client/` and optional `icon.png` sit at the package's root, and the directory
+ * `client/`, optional `icon.png`, and optional `agent.md` sit at the package's
+ * root, and the directory
  * the system installs into is named from the program's own `identity`.
  * The archive itself therefore needs no second naming layer.
  *
@@ -44,6 +45,8 @@ export default async function pack(directory = process.cwd()) {
     }
     if (config.icon)
         file(zip, directory, config.icon, "icon.png", "Program icon");
+    if (config.agent)
+        file(zip, directory, config.agent, "agent.md", "Program agent documentation");
     zip.addFile("program.json", Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n"));
     const archive = `${config.identity}@${version ?? "0.0.0"}.zip`;
     const bytes = zip.toBuffer();
@@ -63,6 +66,7 @@ function program(config, version) {
         version,
         description: config.description,
         icon: config.icon ? "icon.png" : undefined,
+        agent: config.agent ? "agent.md" : undefined,
         ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, startCommand: config.server.startCommand } },
         ...config.client && { client: { location: "client", start: config.client.start, title: config.client.title, size: config.client.size, position: config.client.position, layer: config.client.layer, minimize: config.client.minimize } }
     };

package/dist/project.js

@@ -39,10 +39,12 @@ function coherent(config) {
         throw new Error("A program's identity is kebab-case, because it is also the name of its directory");
     if (!config.server && !config.client)
         throw new Error("A program must have a server half, a client half, or both");
-    for (const field of ["name", "version", "description", "icon"]) {
+    for (const field of ["name", "version", "description", "icon", "agent"]) {
         if (config[field] !== undefined && typeof config[field] !== "string")
             throw new Error(`A program's ${field} must be text`);
     }
+    if (config.agent !== undefined && config.agent.trim().length === 0)
+        throw new Error("A program's agent documentation must be a non-empty path");
     if (config.buildCommand !== undefined && (typeof config.buildCommand !== "string" || config.buildCommand.trim().length === 0))
         throw new Error("A program's buildCommand must be non-empty text");
     for (const half of ["server", "client"]) {

package/dist/template/package.json

@@ -22,7 +22,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.17",
+        "@phreshos/cli": "^0.1.19",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.17",
+  "version": "0.1.19",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,7 +49,7 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.9",
+    "@phreshos/core": "^0.1.12",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"