@vimhead.dev/norn-cli 0.1.0-tip.35725822562.1 → 0.1.0-tip.36148588553.1

package/assets/README.md

@@ -149,8 +149,9 @@ methods, custom providers, and Norn's configuration directory, see
 
 ### 3. Optionally connect your harness
 
-The shipped Pi and Cursor adapters deliver Norn documentation context to your
-harness. Installing Norn alone does not register an adapter. Claude Code, Codex,
+The shipped Pi, Cursor, and Claude Code adapters deliver Norn documentation context and
+[available workflow introductions](docs/cli.md#workflow-introduction) to your
+harness at session start. Installing Norn alone does not register an adapter. Codex
 and other harnesses can [invoke the CLI directly](docs/cli.md#javascript-client-and-other-harnesses).
 
 #### Pi
@@ -183,6 +184,32 @@ outside `PATH`, start Cursor with an executable path:
 NORN_EXECUTABLE=/absolute/path/to/norn cursor .
 ```
 
+#### Claude Code
+
+With Node and `norn` available on `PATH`, run in your terminal:
+
+```bash
+claude plugin marketplace add vimhead/norn
+claude plugin install norn@norn-adapters
+claude
+```
+
+To select a different runtime, launch Claude Code with
+`NORN_EXECUTABLE=/absolute/path/to/norn claude`. The plugin uses that runtime's
+documentation and the workflows in the session's working directory; it does not
+install Norn or configure authentication for Norn agents.
+
+Context is added on startup, `/clear`, and compaction, not again on resume or
+fork. Named-agent sessions (`--agent`) and subagent hook calls are excluded.
+Existing instructions and prompts are preserved. Introduction failures appear as
+hook errors without falling back to another runtime.
+
+To test a checkout without installing the marketplace:
+
+```bash
+claude --plugin-dir /absolute/path/to/norn
+```
+
 Need an adapter for another harness? [Open an issue](https://github.com/vimhead/norn/issues/new)
 with the harness name.
 

package/assets/docs/cli.md

@@ -96,6 +96,31 @@ each argument, without relying on another `norn` installation on PATH.
 inputs without filesystem or process access. Generating the introduction does not
 inject it into prompts or alter Norn agent sessions.
 
+## Workflow introduction
+
+```bash
+norn workflows intro
+```
+
+Returns `{ "intro": "..." }` with caller guidance and an XML advertisement of the
+current project's entrypoints. Each `<workflow>` contains its fully qualified
+`<id>` and caller-facing `<instructions>` inside `<available_norn_workflows>`;
+field values are XML-escaped. Internal steps and argument schemas are omitted.
+For example, the [minimal project](../examples/minimal-workflow/README.md)
+advertises `greet`; its full contract remains available through `workflows inspect greet`.
+
+The command discovers the nearest project from the invocation directory and
+loads current registration modules. No project, or a valid project with no
+entrypoints, returns `{ "intro": "" }` with no preamble or XML wrapper. Invalid
+configuration or incomplete registration fails rather than returning an empty
+or partial advertisement. Like [other discovery commands](projects.md#import-and-reload),
+it evaluates module-level code but does not execute workflows or create run state.
+
+Adapters can request `docs intro` and `workflows intro` from the same selected
+executable and deliver the returned text in that order. Neither command injects
+context itself. The advertisement is a snapshot, not a replacement for live
+workflow listing and inspection after source changes.
+
 ## Discover live contracts
 
 ```bash

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35725822562.1"}
+{"version":"0.1.0-tip.36148588553.1"}

package/assets/packages/cli/src/cli.ts

@@ -67,6 +67,8 @@ import {
 	NORN_PROJECT_FILE_NAME,
 } from "./workflow-loader.ts";
 
+import { loadNornWorkflowsIntro } from "./workflows-intro.ts";
+
 const RUNS_ROOT = join(".norn", "runs");
 const RUN_WAIT_INTERVAL_MS = 1000;
 const CLI_DESCRIPTION =
@@ -215,6 +217,20 @@ const COMMANDS: readonly CliCommand[] = [
 		examples: ["norn workflows list", "norn workflows list --all"],
 		execute: listWorkflows,
 	},
+	{
+		id: "workflows.intro",
+		path: ["workflows", "intro"],
+		description:
+			"Produce caller guidance and an XML advertisement of the current project's entrypoint workflows. Loads project modules but does not execute workflows or deliver context to agents.",
+		usage: "norn workflows intro",
+		output:
+			"JSON object with text under intro. Empty when no project or entrypoints exist; project-loading failures are errors, not partial advertisements.",
+		examples: ["norn workflows intro"],
+		execute: async (args) => {
+			assertNoExtraArgs("workflows intro", args);
+			writeJson({ intro: await loadNornWorkflowsIntro(process.cwd()) });
+		},
+	},
 	{
 		id: "workflows.inspect",
 		path: ["workflows", "inspect"],
@@ -485,6 +501,7 @@ const HELP_COMMAND_ORDER = [
 	"docs.inspect",
 	"docs.intro",
 	"workflows.list",
+	"workflows.intro",
 	"workflows.inspect",
 	"runs.start",
 	"runs.resume",
@@ -513,6 +530,8 @@ const HUMAN_COMMAND_SUMMARIES: Readonly<Record<string, string>> = {
 	"docs.intro":
 		"Produce a compact authoring introduction with local documentation pointers.",
 	"workflows.list": "List Norn workflows.",
+	"workflows.intro":
+		"Advertise current entrypoints with caller instructions as XML.",
 	"workflows.inspect": "Inspect a workflow schema and source.",
 	"runs.start": "Start a workflow run.",
 	"runs.resume": "Resume an interrupted gate or a restored checkpoint.",

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.35725822562.1",
-  "commit": "95e10f8b64ae8220d24420c3b09484f7e7943c3f",
+  "version": "0.1.0-tip.36148588553.1",
+  "commit": "bef15bd5452b3202f93f33f0b33bdf07a48f7ffc",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/assets/packages/cli/src/internal/errors.ts

@@ -1,6 +1,13 @@
 import type { NornWorkflowDiagnostic } from "@vimhead.dev/norn";
 import { AssertError } from "typebox/value";
 
+export class NornProjectNotFoundError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NornProjectNotFoundError";
+	}
+}
+
 export class NornProjectLoadError extends Error {
 	readonly code = "NORN_PROJECT_INVALID";
 	readonly isComplete = false;

package/assets/packages/cli/src/workflow-loader.ts

@@ -24,7 +24,11 @@ import * as typeboxCompileModule from "typebox/compile";
 import * as typeboxSchemaModule from "typebox/schema";
 import * as typeboxValueModule from "typebox/value";
 import { AssertError, Value } from "typebox/value";
-import { errorMessage, NornProjectLoadError } from "./internal/errors.ts";
+import {
+	errorMessage,
+	NornProjectLoadError,
+	NornProjectNotFoundError,
+} from "./internal/errors.ts";
 import {
 	assertCompatibleConfigurationOwners,
 	assertWorkflowDefinition,
@@ -169,7 +173,9 @@ async function findNearestNornProject(cwd: string): Promise<string> {
 		}
 		const parent = dirname(current);
 		if (parent === current)
-			throw new Error(`Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`);
+			throw new NornProjectNotFoundError(
+				`Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`,
+			);
 		current = parent;
 	}
 }

package/assets/packages/cli/src/workflows-intro.ts

@@ -0,0 +1,43 @@
+import type { NornRegisteredWorkflowInfo } from "@vimhead.dev/norn";
+import { NornProjectNotFoundError } from "./internal/errors.ts";
+import { loadNornProject } from "./workflow-loader.ts";
+
+export async function loadNornWorkflowsIntro(cwd: string): Promise<string> {
+	try {
+		const project = await loadNornProject(cwd);
+		return renderNornWorkflowsIntro(project.registry.list());
+	} catch (error) {
+		if (error instanceof NornProjectNotFoundError) return "";
+		throw error;
+	}
+}
+
+export function renderNornWorkflowsIntro(
+	workflows: readonly NornRegisteredWorkflowInfo[],
+): string {
+	const entrypoints = workflows.filter((workflow) => workflow.isEntrypoint);
+	if (entrypoints.length === 0) return "";
+	return [
+		"The following Norn workflows are available in the current project.",
+		"When a task matches, use `workflows inspect <id>` with the runtime specified above to load its current contract.",
+		"Use `workflows list` to refresh this snapshot after workflow changes.",
+		"",
+		"<available_norn_workflows>",
+		...entrypoints.flatMap((workflow) => [
+			"  <workflow>",
+			`    <id>${escapeXml(workflow.id)}</id>`,
+			`    <instructions>${escapeXml(workflow.instructions ?? "")}</instructions>`,
+			"  </workflow>",
+		]),
+		"</available_norn_workflows>",
+	].join("\n");
+}
+
+function escapeXml(value: string): string {
+	return value
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&apos;");
+}

package/assets/packages/core/src/host-introduction.mjs

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process";
+import { Buffer } from "node:buffer";
+import { promisify } from "node:util";
+
+const runExecutable = promisify(execFile);
+const MAX_INTRO_BYTES = 16_384;
+
+function readIntroResponse({ stdout, group }) {
+	const response = JSON.parse(stdout);
+	if (
+		!response ||
+		typeof response !== "object" ||
+		typeof response.intro !== "string" ||
+		(group === "docs" && response.intro.trim().length === 0) ||
+		Buffer.byteLength(response.intro, "utf8") > MAX_INTRO_BYTES
+	)
+		throw new Error("Invalid Norn introduction response");
+	return response.intro;
+}
+
+async function loadIntroduction({ executable, cwd, group }) {
+	const { stdout } = await runExecutable(executable, [group, "intro"], {
+		cwd,
+		timeout: 10_000,
+		maxBuffer: MAX_INTRO_BYTES * 2,
+	});
+	return readIntroResponse({ stdout, group });
+}
+
+export async function loadHostIntroduction({ executable, cwd }) {
+	const [intro, workflowsIntro] = await Promise.all([
+		loadIntroduction({ executable, cwd, group: "docs" }),
+		loadIntroduction({ executable, cwd, group: "workflows" }),
+	]);
+	return `<norn-docs-intro>\n${intro}\n</norn-docs-intro>${workflowsIntro ? `\n\n${workflowsIntro}` : ""}`;
+}

package/dist/cli.js

@@ -64,6 +64,7 @@ import {
   loadNornProject,
   NORN_PROJECT_FILE_NAME
 } from "./workflow-loader.js";
+import { loadNornWorkflowsIntro } from "./workflows-intro.js";
 var RUNS_ROOT = join(".norn", "runs");
 var RUN_WAIT_INTERVAL_MS = 1e3;
 var CLI_DESCRIPTION = "Norn is a harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents. Build workflows with the Norn SDK; use this JSON-native CLI to discover workflows, start or resume runs, inspect evidence, and manage the installed runtime.";
@@ -193,6 +194,18 @@ var COMMANDS = [
     examples: ["norn workflows list", "norn workflows list --all"],
     execute: listWorkflows
   },
+  {
+    id: "workflows.intro",
+    path: ["workflows", "intro"],
+    description: "Produce caller guidance and an XML advertisement of the current project's entrypoint workflows. Loads project modules but does not execute workflows or deliver context to agents.",
+    usage: "norn workflows intro",
+    output: "JSON object with text under intro. Empty when no project or entrypoints exist; project-loading failures are errors, not partial advertisements.",
+    examples: ["norn workflows intro"],
+    execute: async (args) => {
+      assertNoExtraArgs("workflows intro", args);
+      writeJson({ intro: await loadNornWorkflowsIntro(process.cwd()) });
+    }
+  },
   {
     id: "workflows.inspect",
     path: ["workflows", "inspect"],
@@ -441,6 +454,7 @@ var HELP_COMMAND_ORDER = [
   "docs.inspect",
   "docs.intro",
   "workflows.list",
+  "workflows.intro",
   "workflows.inspect",
   "runs.start",
   "runs.resume",
@@ -467,6 +481,7 @@ var HUMAN_COMMAND_SUMMARIES = {
   "docs.inspect": "Locate matching documentation and examples offline.",
   "docs.intro": "Produce a compact authoring introduction with local documentation pointers.",
   "workflows.list": "List Norn workflows.",
+  "workflows.intro": "Advertise current entrypoints with caller instructions as XML.",
   "workflows.inspect": "Inspect a workflow schema and source.",
   "runs.start": "Start a workflow run.",
   "runs.resume": "Resume an interrupted gate or a restored checkpoint.",

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.35725822562.1";
-    readonly commit: "95e10f8b64ae8220d24420c3b09484f7e7943c3f";
+    readonly version: "0.1.0-tip.36148588553.1";
+    readonly commit: "bef15bd5452b3202f93f33f0b33bdf07a48f7ffc";
     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.35725822562.1",
-  "commit": "95e10f8b64ae8220d24420c3b09484f7e7943c3f",
+  "version": "0.1.0-tip.36148588553.1",
+  "commit": "bef15bd5452b3202f93f33f0b33bdf07a48f7ffc",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/dist/internal/errors.d.ts

@@ -1,5 +1,8 @@
 import type { NornWorkflowDiagnostic } from "@vimhead.dev/norn";
 import { AssertError } from "typebox/value";
+export declare class NornProjectNotFoundError extends Error {
+    constructor(message: string);
+}
 export declare class NornProjectLoadError extends Error {
     readonly code = "NORN_PROJECT_INVALID";
     readonly isComplete = false;

package/dist/internal/errors.js

@@ -1,5 +1,11 @@
 // src/internal/errors.ts
 import { AssertError } from "typebox/value";
+var NornProjectNotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NornProjectNotFoundError";
+  }
+};
 var NornProjectLoadError = class extends Error {
   code = "NORN_PROJECT_INVALID";
   isComplete = false;
@@ -31,6 +37,7 @@ function errorMessage(error) {
 }
 export {
   NornProjectLoadError,
+  NornProjectNotFoundError,
   NornRunStoppedError,
   errorMessage,
   schemaErrorMessage

package/dist/workflow-loader.js

@@ -22,7 +22,11 @@ import * as typeboxCompileModule from "typebox/compile";
 import * as typeboxSchemaModule from "typebox/schema";
 import * as typeboxValueModule from "typebox/value";
 import { AssertError, Value } from "typebox/value";
-import { errorMessage, NornProjectLoadError } from "./internal/errors.js";
+import {
+  errorMessage,
+  NornProjectLoadError,
+  NornProjectNotFoundError
+} from "./internal/errors.js";
 import {
   assertCompatibleConfigurationOwners,
   assertWorkflowDefinition,
@@ -126,7 +130,9 @@ async function findNearestNornProject(cwd) {
     }
     const parent = dirname(current);
     if (parent === current)
-      throw new Error(`Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`);
+      throw new NornProjectNotFoundError(
+        `Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`
+      );
     current = parent;
   }
 }

package/dist/workflows-intro.d.ts

@@ -0,0 +1,3 @@
+import type { NornRegisteredWorkflowInfo } from "@vimhead.dev/norn";
+export declare function loadNornWorkflowsIntro(cwd: string): Promise<string>;
+export declare function renderNornWorkflowsIntro(workflows: readonly NornRegisteredWorkflowInfo[]): string;

package/dist/workflows-intro.js

@@ -0,0 +1,37 @@
+// src/workflows-intro.ts
+import { NornProjectNotFoundError } from "./internal/errors.js";
+import { loadNornProject } from "./workflow-loader.js";
+async function loadNornWorkflowsIntro(cwd) {
+  try {
+    const project = await loadNornProject(cwd);
+    return renderNornWorkflowsIntro(project.registry.list());
+  } catch (error) {
+    if (error instanceof NornProjectNotFoundError) return "";
+    throw error;
+  }
+}
+function renderNornWorkflowsIntro(workflows) {
+  const entrypoints = workflows.filter((workflow) => workflow.isEntrypoint);
+  if (entrypoints.length === 0) return "";
+  return [
+    "The following Norn workflows are available in the current project.",
+    "When a task matches, use `workflows inspect <id>` with the runtime specified above to load its current contract.",
+    "Use `workflows list` to refresh this snapshot after workflow changes.",
+    "",
+    "<available_norn_workflows>",
+    ...entrypoints.flatMap((workflow) => [
+      "  <workflow>",
+      `    <id>${escapeXml(workflow.id)}</id>`,
+      `    <instructions>${escapeXml(workflow.instructions ?? "")}</instructions>`,
+      "  </workflow>"
+    ]),
+    "</available_norn_workflows>"
+  ].join("\n");
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+export {
+  loadNornWorkflowsIntro,
+  renderNornWorkflowsIntro
+};

package/package.json

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