@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/sdk/src/files.ts

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { writeTextAtomically } from "@vimhead.dev/norn-core/atomic-files";
+
+const ownerSchema = z.strictObject({
+	token: z.uuid(),
+	pid: z.number().int().positive(),
+	host: z.string(),
+	target: z.string(),
+});
+
+export class NornFileCoordinator {
+	private readonly lockRoot: string;
+
+	constructor(private readonly input: { readonly lockRoot: string; readonly waitTimeoutMs: number }) {
+		if (!Number.isSafeInteger(input.waitTimeoutMs) || input.waitTimeoutMs <= 0) throw new Error("Lock wait timeout must be a positive integer");
+		this.lockRoot = resolve(input.lockRoot);
+	}
+
+	async withExclusiveLock<T>(path: string, operation: (lockedPath: string) => Promise<T>): Promise<T> {
+		const target = await this.resolveTarget(path);
+		await mkdir(this.lockRoot, { recursive: true, mode: 0o700 });
+		const key = createHash("sha256").update(target).digest("hex");
+		const lockPath = join(this.lockRoot, `${key}.lock`);
+		const stagingPath = await mkdtemp(join(this.lockRoot, `${key}.pending-`));
+		const token = randomUUID();
+		const marker = `${token}.json`;
+		return this.withCleanup({
+			operation: async () => {
+				await writeFile(join(stagingPath, marker), JSON.stringify({ token, pid: process.pid, host: hostname(), target }), { mode: 0o600 });
+				await this.acquire({ stagingPath, lockPath, target });
+				return this.withCleanup({
+					operation: () => operation(target),
+					cleanup: async () => {
+						await unlink(join(lockPath, marker));
+						await this.removeEmptyLock(lockPath);
+					},
+				});
+			},
+			cleanup: () => rm(stagingPath, { recursive: true, force: true }),
+		});
+	}
+
+	async readText(path: string): Promise<string> {
+		return this.withExclusiveLock(path, (lockedPath) => readFile(lockedPath, "utf8"));
+	}
+
+	async writeText(path: string, content: string): Promise<void> {
+		await mkdir(dirname(path), { recursive: true });
+		await this.withExclusiveLock(path, (lockedPath) => writeTextAtomically(lockedPath, content));
+	}
+
+	private async withCleanup<T>(input: { readonly operation: () => Promise<T>; readonly cleanup: () => Promise<void> }): Promise<T> {
+		let result: T;
+		try {
+			result = await input.operation();
+		} catch (error) {
+			try { await input.cleanup(); }
+			catch (cleanupError) { throw new AggregateError([error, cleanupError], "File operation and lock cleanup failed"); }
+			throw error;
+		}
+		await input.cleanup();
+		return result;
+	}
+
+	private async resolveTarget(path: string): Promise<string> {
+		try {
+			return await realpath(path);
+		} catch (error) {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+			const entry = await lstat(path).catch((error: unknown) => {
+				if (isNodeError(error) && error.code === "ENOENT") return undefined;
+				throw error;
+			});
+			if (entry?.isSymbolicLink()) throw new Error(`Cannot lock a dangling symbolic link: ${path}`);
+			return join(await realpath(dirname(path)), basename(path));
+		}
+	}
+
+	private async acquire(input: { readonly stagingPath: string; readonly lockPath: string; readonly target: string }): Promise<void> {
+		const deadline = Date.now() + this.input.waitTimeoutMs;
+		while (true) {
+			try {
+				await rename(input.stagingPath, input.lockPath);
+				return;
+			} catch (error) {
+				if (!isNodeError(error) || !["ENOTEMPTY", "EEXIST"].includes(error.code ?? "")) throw error;
+			}
+			await this.reclaimDeadOwner(input);
+			if (Date.now() >= deadline) throw new Error(`Timed out waiting for file lock: ${input.target}`);
+			await delay(10);
+		}
+	}
+
+	private async reclaimDeadOwner(input: { readonly lockPath: string; readonly target: string }): Promise<void> {
+		try {
+			const entries = await readdir(input.lockPath);
+			if (entries.length === 0) return;
+			if (entries.length !== 1) throw new Error(`Invalid file lock ownership: ${input.lockPath}`);
+			const marker = entries[0];
+			const owner = ownerSchema.parse(JSON.parse(await readFile(join(input.lockPath, marker), "utf8")));
+			if (marker !== `${owner.token}.json` || owner.target !== input.target || owner.host !== hostname()) {
+				throw new Error(`Incompatible file lock ownership: ${input.lockPath}`);
+			}
+			try {
+				process.kill(owner.pid, 0);
+				return;
+			} catch (error) {
+				if (isNodeError(error) && error.code === "EPERM") return;
+				if (!isNodeError(error) || error.code !== "ESRCH") throw error;
+			}
+			// A delayed reaper must never remove a successor's differently named marker.
+			await unlink(join(input.lockPath, marker));
+			await this.removeEmptyLock(input.lockPath);
+		} catch (error) {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		}
+	}
+
+	private async removeEmptyLock(path: string): Promise<void> {
+		try {
+			await rmdir(path);
+		} catch (error) {
+			if (!isNodeError(error) || !["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code ?? "")) throw error;
+		}
+	}
+}
+
+export function createRunFileCoordinator(runRoot: string): NornFileCoordinator {
+	return new NornFileCoordinator({ lockRoot: join(runRoot, "locks"), waitTimeoutMs: 30_000 });
+}

package/assets/packages/sdk/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./api.ts";
+export { NornFileCoordinator } from "./files.ts";
+export * from "./resources.ts";
+export * from "./agent-resource-adapter.ts";
+export * from "./state-adapter.ts";
+export * from "./seer/index.ts";

package/assets/packages/sdk/src/resources.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+import type { NornFileCoordinator } from "./files.ts";
+
+export type NornResourceContext = {
+	readonly mode: "create" | "open";
+	readonly directory: string;
+	readonly files: NornFileCoordinator;
+};
+
+export type NornResourceDefinition<T> = {
+	readonly name: string;
+	readonly kind: string;
+	readonly configuration: z.infer<ReturnType<typeof z.json>>;
+	initialize(context: NornResourceContext): Promise<T>;
+};
+
+export type NornResources = {
+	readonly files: NornFileCoordinator;
+	ensure<T>(definition: NornResourceDefinition<T>): Promise<T>;
+};

package/assets/packages/sdk/src/schema.ts

@@ -0,0 +1,48 @@
+import type { NornAnyWorkflowDeclaration } from "./api.ts";
+
+export function assertWorkflowMetadata(workflow: NornAnyWorkflowDeclaration): void {
+	if (workflow.instructions !== undefined && (typeof workflow.instructions !== "string" || workflow.instructions.trim().length === 0)) {
+		throw new Error(`Workflow instructions must be a nonempty string: ${workflow.id}`);
+	}
+	if (workflow.isEntrypoint && workflow.instructions === undefined) {
+		throw new Error(`Entrypoint workflow requires instructions: ${workflow.id}`);
+	}
+}
+
+export function unwrapSchema(schema: unknown): unknown {
+	let current = schema;
+	while (true) {
+		const def = schemaDef(current);
+		if (["optional", "nullable", "default", "catch", "readonly", "prefault"].includes(def.type ?? "") && def.innerType) {
+			current = def.innerType;
+			continue;
+		}
+		return current;
+	}
+}
+
+export function schemaShape(schema: unknown): Record<string, unknown> {
+	const shape = schemaDef(unwrapSchema(schema)).shape;
+	if (!shape) return {};
+	return typeof shape === "function" ? shape() as Record<string, unknown> : shape as Record<string, unknown>;
+}
+
+export function schemaType(schema: unknown): string | undefined {
+	return schemaDef(unwrapSchema(schema)).type;
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+type ZodDef = {
+	readonly type?: string;
+	readonly innerType?: unknown;
+	readonly shape?: unknown;
+};
+
+function schemaDef(schema: unknown): ZodDef {
+	if (!schema || typeof schema !== "object") return {};
+	const candidate = schema as { _def?: ZodDef; def?: ZodDef };
+	return candidate._def ?? candidate.def ?? {};
+}

package/assets/packages/sdk/src/seer/config.ts

@@ -0,0 +1,62 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export type NornSeerModeConfig = {
+	readonly writableRoots: readonly string[];
+};
+
+export type NornResolvedSeerModeConfig = {
+	readonly configPath: string;
+	readonly projectRoot: string;
+	readonly writableRoots: readonly string[];
+};
+
+type ResolveSeerModeConfigInput = {
+	readonly configPath: string;
+	readonly configRoot: string;
+	readonly seerMode: NornSeerModeConfig | undefined;
+};
+
+export function resolveSeerModeConfig(input: ResolveSeerModeConfigInput): NornResolvedSeerModeConfig | undefined {
+	if (!input.seerMode) return undefined;
+	if (input.seerMode.writableRoots.length === 0) throw new Error("Norn seerMode.writableRoots must not be empty");
+	const projectRoot = resolve(input.configRoot);
+	const writableRoots = Array.from(new Set(input.seerMode.writableRoots.map((path) => resolveWritableRoot(projectRoot, path))));
+	return { configPath: input.configPath, projectRoot, writableRoots };
+}
+
+export function assertSeerModeWritablePath(seerMode: NornResolvedSeerModeConfig, cwd: string, path: string): string {
+	const resolvedPath = resolveSeerModePath(seerMode, cwd, path);
+	if (!isSeerModeWritableResolvedPath(seerMode, resolvedPath)) {
+		throw new Error(`Path is outside Norn seerMode writable roots: ${path}`);
+	}
+	return resolvedPath;
+}
+
+export function isSeerModeWritablePath(seerMode: NornResolvedSeerModeConfig, cwd: string, path: string): boolean {
+	return isSeerModeWritableResolvedPath(seerMode, resolveSeerModePath(seerMode, cwd, path));
+}
+
+function resolveWritableRoot(projectRoot: string, path: string): string {
+	if (path.length === 0) throw new Error("Norn seerMode writable root must not be empty");
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(projectRoot, path);
+	if (!isInsideOrEqual(projectRoot, resolvedPath)) throw new Error(`Norn seerMode writable root escapes project root: ${path}`);
+	return resolvedPath;
+}
+
+function resolveSeerModePath(seerMode: NornResolvedSeerModeConfig, cwd: string, path: string): string {
+	if (path.length === 0) throw new Error("Norn seerMode path must not be empty");
+	const resolvedCwd = resolve(cwd);
+	if (!isInsideOrEqual(seerMode.projectRoot, resolvedCwd)) throw new Error(`Norn seerMode cwd escapes project root: ${cwd}`);
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedCwd, path);
+	if (!isInsideOrEqual(seerMode.projectRoot, resolvedPath)) return resolvedPath;
+	return resolvedPath;
+}
+
+function isSeerModeWritableResolvedPath(seerMode: NornResolvedSeerModeConfig, path: string): boolean {
+	return seerMode.writableRoots.some((root) => isInsideOrEqual(root, path));
+}
+
+function isInsideOrEqual(root: string, path: string): boolean {
+	const pathFromRoot = relative(root, path);
+	return pathFromRoot === "" || (!pathFromRoot.startsWith(`..${sep}`) && pathFromRoot !== ".." && !isAbsolute(pathFromRoot));
+}

package/assets/packages/sdk/src/seer/index.ts

@@ -0,0 +1,7 @@
+export {
+	assertSeerModeWritablePath,
+	isSeerModeWritablePath,
+	resolveSeerModeConfig,
+	type NornResolvedSeerModeConfig,
+	type NornSeerModeConfig,
+} from "./config.ts";

package/assets/packages/sdk/src/state-adapter.ts

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { z } from "zod";
+import type { NornWorkflowState, NornWorkflowStateDefinition } from "./api.ts";
+import type { NornAgentResourceAdapter } from "./agent-resource-adapter.ts";
+
+export type NornStateFieldAccess = {
+	readonly field: NornWorkflowStateDefinition;
+	readonly access: "read" | "write" | "read-write";
+};
+
+const pageParameters = {
+	offset: Type.Integer({ minimum: 0, description: "Zero-based UTF-16 offset into the serialized JSON. Start at 0." }),
+	limit: Type.Integer({ minimum: 1, maximum: 10000 }),
+};
+
+export function StateAdapter(input: { readonly state: NornWorkflowState; readonly fields: readonly NornStateFieldAccess[] }): NornAgentResourceAdapter {
+	const fields = new Map(input.fields.map((grant) => [grant.field.id, grant]));
+	if (fields.size !== input.fields.length || fields.size === 0) throw new Error("State attachment requires unique, explicitly selected fields");
+	const selectField = (key: string, access: "read" | "write") => {
+		const grant = fields.get(key);
+		if (!grant || (grant.access !== access && grant.access !== "read-write")) throw new Error(`State ${access} is not attached: ${key}`);
+		return grant.field;
+	};
+	return {
+		name: "norn.state",
+		async bind() {
+			return {
+				tools: [
+					defineTool({
+						name: "norn_state_list",
+						label: "Attached workflow state",
+						description: "List only attached workflow-state field IDs, permissions and value schemas. JSON is paginated; use nextOffset until null.",
+						parameters: Type.Object(pageParameters),
+						async execute(_id, params) {
+							return serializePage({ value: [...fields.values()].map(({ field, access }) => ({ id: field.id, access, schema: z.toJSONSchema(field.schema, { io: "input" }) })), ...params });
+						},
+					}),
+					defineTool({
+						name: "norn_state_get",
+						label: "Read workflow state",
+						description: "Read a selected workflow-state field. Unset fields return isSet:false. JSON is paginated; concurrent writes can change later pages, so compare revision before combining pages.",
+						parameters: Type.Object({ key: Type.String(), ...pageParameters }),
+						async execute(_id, params) {
+							const value = await input.state.getOptional(selectField(params.key, "read"));
+							return serializePage({ value: value === undefined ? { isSet: false } : { isSet: true, value }, ...params });
+						},
+					}),
+					defineTool({
+						name: "norn_state_set",
+						label: "Write workflow state",
+						description: "Set an explicitly writable workflow-state field. Validate the value against its schema from norn_state_list. A get followed by set is not a transaction.",
+						parameters: Type.Object({ key: Type.String(), value: Type.Unknown() }),
+						async execute(_id, params, signal) {
+							signal?.throwIfAborted();
+							const field = selectField(params.key, "write");
+							await input.state.set(field, params.value);
+							return { content: [{ type: "text", text: "Workflow state saved." }], details: {} };
+						},
+					}),
+				],
+				async dispose() {},
+			};
+		},
+	};
+}
+
+function serializePage(input: { readonly value: unknown; readonly offset: number; readonly limit: number }) {
+	const serialized = JSON.stringify(input.value);
+	if (!Number.isInteger(input.offset) || input.offset < 0 || !Number.isInteger(input.limit) || input.limit < 1 || input.limit > 10000) throw new Error("Invalid state output page");
+	const end = Math.min(serialized.length, input.offset + input.limit);
+	const details = { text: serialized.slice(input.offset, end), nextOffset: end < serialized.length ? end : null, revision: createHash("sha256").update(serialized).digest("hex") };
+	return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details };
+}

package/assets/setup/providers.md

@@ -0,0 +1,128 @@
+# Providers and authentication
+
+`norn pi` runs the Pi CLI bundled with the selected Norn installation. It needs
+neither a separate Pi installation nor a Norn project. Everything after `pi` is
+forwarded to Pi, including its terminal UI, package commands, and output modes:
+
+```bash
+norn pi --version
+norn pi --help
+norn pi
+```
+
+In the interactive session, use `/login` to authenticate. Open `/model`, highlight
+the desired model, and press **Ctrl+S** to save it as the startup default. Selecting
+a model is not the same as saving a startup default. Use `/quit` to exit.
+Configure these before launching Norn agents: detached execution cannot conduct
+interactive login. Authentication in the outer harness does not automatically
+authenticate a Norn agent's provider.
+
+## Norn configuration
+
+The proxy and Norn agents share Norn's agent directory, normally `~/.norn/agent/`.
+It is independent of the outer Pi harness's global configuration:
+
+- `settings.json` — installed packages and default provider/model
+- `auth.json` — saved API keys and OAuth credentials
+- `models.json` — custom endpoints, models, and authentication configuration
+
+`NORN_AGENT_DIR` selects another directory. Set it consistently for both
+`norn pi` and workflow execution. A programmatic runtime caller supplying `agentDir`
+must point the setup command at that same directory. Norn does not use an inherited
+`PI_CODING_AGENT_DIR` to select its global configuration. Existing Pi packages and
+credentials are not imported or linked: install providers and authenticate through
+`norn pi`, even when Pi is the outer harness.
+
+Project-local `.pi` settings and extension discovery still depend on the working
+directory; installing a provider globally avoids making
+it available only in one project or worktree.
+
+Login is optional when credentials are supplied another way. Norn agents inherit
+provider environment variables such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
+Custom providers can resolve environment variables or secret-manager commands
+through `models.json`. Keep credentials out of project files and version control.
+Finding a configured key or listing a model is not proof that a provider accepts it.
+
+## Third-party provider packages
+
+Pi provider extensions are separate from Norn workflow plugins and outer-harness
+adapters. They register providers through Pi's APIs; do not put them in
+`norn.project.json` or install them only in Cursor's plugin marketplace.
+
+Use `norn pi install` with the package's published npm spec or Git URL. For example:
+
+```bash
+norn pi install npm:pi-cursor-sdk@0.3.6
+norn pi --list-models cursor
+norn pi
+```
+
+This installs into Norn's global configuration. Select the new provider using
+`/model`. Agent resource discovery and model precedence are covered in
+[Norn agents](../docs/agents.md#prompts-tools-and-resource-loading).
+Use `norn pi list` to inspect installations and `norn pi remove <source>` to remove
+one. Upgrade bundled Pi by upgrading Norn, not by using Pi's self-update command.
+`norn pi update --extensions` updates unpinned extension packages.
+
+Review third-party packages before installation: extensions and dependency install
+scripts execute code with the user's permissions. npm packages require Node/npm;
+Git sources additionally require Git. A standalone Norn binary does not bundle
+those installers or every third-party package's native dependencies. Check package
+requirements against `norn pi --version` and the local platform.
+
+### Cursor SDK example
+
+[pi-cursor-sdk](https://pi.dev/packages/pi-cursor-sdk) registers the `cursor`
+provider. Its API key must be a **Cursor SDK API key** (user or service account),
+not a Team Admin key. It does not reuse Cursor Desktop or Agent CLI login.
+
+After installation, run `/login cursor` inside `norn pi` and enter the SDK key,
+or supply `CURSOR_API_KEY` to Norn's launching environment. Select a Cursor model
+with `/model`. A newly started session reloads the provider; its model listing can
+contain fallback models even without working credentials.
+
+Keep the provider's **local runtime and Pi tool bridge enabled** for Norn agents.
+Norn requires its structured-response tool, and attached resources also expose Pi
+tools. The provider's cloud mode does not expose that local bridge. Cursor-native
+tools are a separate surface: restricting Norn's `tools` list does not disable
+Cursor's own tools or ambient configuration. See the package's documentation for
+its runtime and isolation controls.
+
+Installation and fallback-model discovery for version 0.3.6 were exercised through
+a standalone Norn binary without credentials. Authenticated Cursor inference and
+its Norn response-tool bridge require a separate live check; model discovery alone
+does not establish end-to-end compatibility.
+
+## Custom endpoints without an extension
+
+For a provider using an existing API protocol, add its configuration under
+`providers` in the shared `models.json`, preserving existing entries:
+
+```json
+{
+  "providers": {
+    "team-gateway": {
+      "baseUrl": "https://gateway.example.com/v1",
+      "api": "openai-completions",
+      "apiKey": "$TEAM_GATEWAY_API_KEY",
+      "models": [{ "id": "team-model" }]
+    }
+  }
+}
+```
+
+Set `TEAM_GATEWAY_API_KEY` in the launching environment, then select the model
+through `norn pi`. A provider with a different protocol or custom OAuth flow needs
+a compatible Pi provider extension, not just an `auth.json` entry. Use that
+extension's documented authentication method; Norn does not duplicate its login
+or token-refresh implementation.
+
+## Standalone assets
+
+Compiled Norn includes the bundled Pi version metadata, themes, documentation,
+examples, and export assets. It extracts and verifies them in a content-specific
+cache before loading Pi. `NORN_PI_CACHE_DIR` overrides its root; otherwise it uses
+`~/Library/Caches/norn/pi` on macOS, `$XDG_CACHE_HOME/norn/pi` (or
+`~/.cache/norn/pi`) on Linux, and `%LOCALAPPDATA%/norn/pi` on Windows.
+The asset cache is not the credential directory. A modified or incomplete entry
+causes an error naming the entry to remove before retrying.

package/assets/setup/releases.md

@@ -0,0 +1,76 @@
+# Rolling releases
+
+The public npm packages are `@vimhead.dev/norn`, `@vimhead.dev/norn-cli`, and
+`@vimhead.dev/pi-norn`. The root and core workspaces are private.
+
+## Local preparation
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+pnpm pack:dry
+```
+
+`pack:dry` writes real pnpm tarballs and a checksum manifest into `dist/npm/`;
+it does not publish. pnpm rewrites the CLI's workspace dependency to the exact
+Norn library version. Consumer builds inline private core code.
+
+## One-time npm bootstrap
+
+An npm owner with access to the `vimhead.dev` organization must publish each new
+package before configuring its trusted publisher. Use a disposable checkout so
+release version stamping does not modify the development checkout:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+git worktree add --detach /tmp/norn-bootstrap HEAD
+cd /tmp/norn-bootstrap
+pnpm install --frozen-lockfile
+pnpm release:prepare 0.1.0-tip.0 "$(git rev-parse HEAD)"
+pnpm release:pack
+pnpm test
+pnpm release:publish --interactive
+```
+
+Choose an unused prerelease version if `0.1.0-tip.0` already exists. The publication
+command prompts through npm for any required authentication/2FA; never put
+credentials in repository files. It publishes the library before the CLI and
+adapter, with public access and the `tip` tag, never `latest`.
+
+For **each** package, configure an npm trusted publisher:
+
+- Provider: GitHub Actions
+- Organization/user: `vimhead`
+- Repository: `norn`
+- Workflow filename: `release.yml`
+- Environment: unset (the workflow does not name one)
+- Allowed action: enable direct `npm publish`, not only staged publishing
+
+Use npm's [trusted-publisher settings](https://docs.npmjs.com/trusted-publishers/).
+GitHub-hosted runners request OIDC credentials through `id-token: write`; no npm
+publishing token is stored in GitHub secrets. Public releases include provenance.
+
+## Continuous tip publication and recovery
+
+After a successful `Test` run on `main`, `Release Tip` stamps all three packages
+with `0.1.0-tip.<GitHub-run-id>.<attempt>` and the tested commit. It validates and
+packs npm artifacts, builds standalone binaries, then publishes only if the
+selected commit is still `main`. Manual dispatch performs the same checks.
+Only after all npm packages are verified does it update the GitHub `tip` release.
+
+npm versions are immutable. A workflow rerun gets a new attempt/version, so a
+partial prior publication is retained rather than overwritten. Repeating the
+publication command for the same artifacts skips an existing package only when
+its integrity and `tip` version match; conflicting bytes or a moved tag fail
+closed and require a new version. Completed npm publication followed by a GitHub
+failure can likewise be repaired by rerunning the workflow.
+
+npm tags move package by package; npm and GitHub do not provide a cross-registry
+transaction. The CLI always uses its exact library dependency, even during a
+partial rollout. Install that version of `@vimhead.dev/norn` for matching editor
+types rather than assuming independently read `tip` tags are atomic.
+
+Trusted publishing authenticates `npm publish`, not general tag-management
+commands. The workflow sets `tip` through publication itself; it does not rely on
+`npm dist-tag` or a long-lived token for a separate promotion step.