@vimhead.dev/norn-cli 0.1.0-tip.35347037721.1 → 0.1.0-tip.35359392805.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Zub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/README.md

@@ -1,21 +1,64 @@
 # Norn
 
-Norn is a harness-agnostic workflow framework and runtime built primarily for
-agents. Use the Norn SDK to write reusable agent-driven and code-driven TypeScript
-workflows, then discover, run, inspect, and recover them through the CLI.
-
-Norn is intended as a portable replacement for harness-specific subagents and
-workflow extensions. Use it from Claude Code, Pi, Codex, or any other harness
-that can invoke its CLI.
-
-Norn agents are powered by the bundled, open-source and extensible
-[Pi coding agent](https://pi.dev). Your outer harness does not need to be Pi,
-and code-only workflows do not require a model.
-
-- [Documentation index](docs/README.md) — focused references by capability
-- [Create → run → change a workflow](examples/minimal-workflow/README.md) — code-driven, no model required
-- [Norn agent → saved artifact → analysis](examples/agent-then-analysis/README.md) — agent-driven, with a recoverable transition
-- [Norn SDK types](packages/sdk/src/api.ts)
+Norn is a portable runtime for reusable agent-driven and code-driven TypeScript
+workflows. Author them with the SDK, then discover, run, inspect, and recover them
+through the CLI from any harness. Agents run on the bundled
+[Pi coding agent](https://pi.dev); code-only workflows need no model.
+
+## Getting started
+
+1. [Install Norn](#installation), including agent authentication.
+
+2. **Combine an agent with code.** The agent writes a summary; code saves it as an artifact.
+
+   ```ts
+   import { definePlugin, definePluginManifest } from "@vimhead.dev/norn";
+   import { Type } from "typebox";
+
+   const manifest = definePluginManifest({
+     id: "summary",
+     workflows: {
+       write: {
+         isEntrypoint: true,
+         instructions: "Summarize supplied text and save the result.",
+         params: Type.Object({ text: Type.String() }),
+       },
+     },
+   });
+
+   export default definePlugin(manifest, {
+     workflows: {
+       write: {
+         async execute(run, { text }) {
+           const summary = await run.agents.prompt({
+             label: "summarize",
+             tools: [],
+             prompt: `Summarize this text in one sentence:\n${text}`,
+             response: Type.Object({ text: Type.String() }),
+           });
+           const artifact = await run.artifacts.write("summary.txt", summary.text);
+           return run.complete({ artifacts: { summary: artifact } });
+         },
+       },
+     },
+   });
+   ```
+
+   [Full example and project configuration](examples/getting-started/README.md)
+
+3. **Run it** from the example directory:
+
+   ```sh
+   printf '%s\n' '{"params":{"text":"Norn workflows combine agents and code. They run from any harness through the CLI."}}' \
+     | norn runs start summary.write
+
+   norn runs wait <run-id>
+   ```
+
+   Replace `<run-id>` with the ID returned by `start`.
+
+See the [documentation index](docs/README.md) for focused references and the
+[SDK types](packages/sdk/src/api.ts) for API details.
 
 ## Installation
 

package/assets/examples/getting-started/README.md

@@ -0,0 +1,26 @@
+# Combine an agent with code
+
+The agent summarizes supplied text; code saves the summary as `summary.txt`.
+The complete workflow is in [plugin.ts](plugin.ts), registered by
+[norn.project.json](norn.project.json).
+
+## Setup and run
+
+[Install Norn](../../README.md#installation), including agent authentication and a
+default model. This example makes a live model call. No local SDK installation or
+compilation step is required.
+
+Copy this directory to a writable task directory and `cd` into the copy, keeping
+[the runtime matched to the example](../../docs/cli.md#select-the-runtime).
+Then follow [Getting started, step 3](../../README.md#getting-started) to run it.
+
+## Inspect the result
+
+`runs wait` returns the run details. Check that `run.status` is `completed`;
+a successful CLI exit alone does not mean the workflow succeeded. The outcome's
+`metadata.artifacts.summary` refers to `summary.txt` under
+`.norn/runs/<run-id>/current/artifacts/`. Read it to assess the summary itself.
+
+Change the prompt or supply different text to reuse the workflow.
+[Norn agents](../../docs/agents.md) covers structured responses, model selection,
+and inherited resources; `tools: []` is not a security sandbox.

package/assets/examples/getting-started/norn.project.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "plugins": ["./plugin.ts"]
+}

package/assets/examples/getting-started/plugin.ts

@@ -0,0 +1,30 @@
+import { definePlugin, definePluginManifest } from "@vimhead.dev/norn";
+import { Type } from "typebox";
+
+const manifest = definePluginManifest({
+	id: "summary",
+	workflows: {
+		write: {
+			isEntrypoint: true,
+			instructions: "Summarize supplied text and save the result.",
+			params: Type.Object({ text: Type.String() }),
+		},
+	},
+});
+
+export default definePlugin(manifest, {
+	workflows: {
+		write: {
+			async execute(run, { text }) {
+				const summary = await run.agents.prompt({
+					label: "summarize",
+					tools: [],
+					prompt: `Summarize this text in one sentence:\n${text}`,
+					response: Type.Object({ text: Type.String() }),
+				});
+				const artifact = await run.artifacts.write("summary.txt", summary.text);
+				return run.complete({ artifacts: { summary: artifact } });
+			},
+		},
+	},
+});

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35347037721.1"}
+{"version":"0.1.0-tip.35359392805.1"}

package/assets/packages/cli/src/generated-build-info.ts

@@ -2,8 +2,8 @@ import type { NornBuildInfo } from "./build-info.ts";
 
 export const NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35347037721.1",
-  "commit": "6b26f2586addf47108400ac882c53288788e187d",
+  "version": "0.1.0-tip.35359392805.1",
+  "commit": "f958006ca0ae3752060727c5b76b2ac1a008b103",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/dist/generated-build-info.d.ts

@@ -1,7 +1,7 @@
 export declare const NORN_GENERATED_BUILD_INFO: {
     readonly kind: "npm-registry";
-    readonly version: "0.1.0-tip.35347037721.1";
-    readonly commit: "6b26f2586addf47108400ac882c53288788e187d";
+    readonly version: "0.1.0-tip.35359392805.1";
+    readonly commit: "f958006ca0ae3752060727c5b76b2ac1a008b103";
     readonly packageSpec: "@vimhead.dev/norn-cli@tip";
     readonly upgrade: {
         readonly supported: false;

package/dist/generated-build-info.js

@@ -1,8 +1,8 @@
 // src/generated-build-info.ts
 var NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35347037721.1",
-  "commit": "6b26f2586addf47108400ac882c53288788e187d",
+  "version": "0.1.0-tip.35359392805.1",
+  "commit": "f958006ca0ae3752060727c5b76b2ac1a008b103",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimhead.dev/norn-cli",
-  "version": "0.1.0-tip.35347037721.1",
+  "version": "0.1.0-tip.35359392805.1",
   "description": "Harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents.",
   "type": "module",
   "license": "MIT",
@@ -42,8 +42,8 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",
     "jiti": "^2.7.0",
-    "typebox": "^1.3.33",
-    "@vimhead.dev/norn": "0.1.0-tip.35347037721.1"
+    "typebox": "^1.3.34",
+    "@vimhead.dev/norn": "0.1.0-tip.35359392805.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.ts"