@thehumanpatternlab/hpl 0.0.1-alpha.5 → 0.0.1-alpha.6

package/README.md

@@ -1,42 +1,173 @@
+<!--
+  HPL CLI
+  The Human Pattern Lab
+
+  This README is written for humans.
+  Design rationale lives in DESIGN.md.
+-->
+
 # HPL CLI (Alpha) 🧭🦊
 
-<span>
-  <img src="https://img.shields.io/badge/AI--Forward%20CLI-black?style=flat-square" />
-  <img src="https://img.shields.io/badge/automation--safe%20by%20design-8b5cf6?style=flat-square" />
-</span>
- 
- [![Carmel Judgment Protocol 😼](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg)](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml)
+![AI-Forward CLI](https://img.shields.io/badge/AI--Forward%20CLI-black?style=flat-square)
+![automation-safe by design](https://img.shields.io/badge/automation--safe%20by%20design-8b5cf6?style=flat-square)
+![npm (alpha)](https://img.shields.io/npm/v/@thehumanpatternlab/hpl/alpha?label=alpha&color=8b5cf6&style=flat-square)
+![Carmel Judgment](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg)
+
+> **Status:** Alpha  
+> A modern, automation-safe CLI for The Human Pattern Lab.
+
+**HPL** is the official command-line interface for **The Human Pattern Lab**.
+
+Formerly developed under the codename **Skulk**, HPL is built to work just as well for humans at the keyboard as it does for automation, CI, and agent-driven workflows.
+
+This package is in **active alpha development**. Interfaces are stabilizing, but iteration is expected.
+
+---
+
+## What HPL Connects To
+
+HPL is a deterministic bridge between:
+
+- the **Human Pattern Lab Content Repository** (source of truth)
+- the **Human Pattern Lab API** (runtime index and operations)
+
+Written content lives as Markdown in a dedicated content repository.  
+The API syncs and indexes that content so it can be rendered by user interfaces.
+
+By default, HPL targets a Human Pattern Lab API instance. You can override the API endpoint with `--base-url` to use staging or a self-hosted deployment of the same API.
+
+> Note: `--base-url` is intended for alternate deployments of the Human Pattern Lab API, not arbitrary third-party APIs.
+
+---
+
+## Authentication
+
+HPL supports token-based authentication via the `HPL_TOKEN` environment variable.
+
+```bash
+export HPL_TOKEN="your-api-token"
+```
+
+(Optional) Override the API endpoint:
+
+```bash
+export HPL_BASE_URL="https://api.thehumanpatternlab.com"
+```
+
+> `HPL_BASE_URL` should point to the **root** of a Human Pattern Lab API deployment.  
+> Do not include additional path segments.
+
+Some API endpoints may require authentication depending on server configuration.
+
+---
+
+## Quick Start
+
+### Install (alpha)
+
+```bash
+npm install -g @thehumanpatternlab/hpl@alpha
+```
+
+### Sync Lab Notes from the content repository
+
+```bash
+hpl notes sync --content-repo AdaInTheLab/the-human-pattern-lab-content
+```
 
-Contract-first CLI for The Human Pattern Lab.
+This pulls structured Markdown content from the repository and synchronizes it into the Human Pattern Lab system.
 
-## Install (local dev)
+### Machine-readable output
 
 ```bash
-npm install
-npm run dev -- --help
+hpl --json notes sync
 ```
 
-## Config
+---
 
-- `HPL_API_BASE_URL` (default: `https://api.thehumanpatternlab.com`)
+## Content Source Configuration (Optional)
 
-## Commands (MVP)
+By default, `notes sync` expects a content repository with the following structure:
 
-- `hpl version`
-- `hpl capabilities`
-- `hpl health`
-- `hpl notes list [--limit N]`
-- `hpl notes get <slug> [--raw]`
+```text
+labnotes/
+  en/
+    *.md
+  ko/
+    *.md
+```
 
-## JSON contract
+You may pin a default content repository using an environment variable:
 
-Add `--json` to emit machine-readable JSON only on stdout.
+```bash
+export HPL_CONTENT_REPO="AdaInTheLab/the-human-pattern-lab-content"
+```
 
-### Examples
+This allows `hpl notes sync` to run without explicitly passing `--content-repo`.
+
+---
+
+## Commands
+
+```text
+hpl <domain> <action> [options]
+```
+
+### notes
+
+- `hpl notes list`
+- `hpl notes get <slug>`
+- `hpl notes sync --content-repo <owner/name|url>`
+- `hpl notes sync --dir <path>` (advanced / local development)
+
+### health
+
+```bash
+hpl health
+```
+
+### version
 
 ```bash
-hpl capabilities --json
-hpl health --json
-hpl notes list --json
-hpl notes get the-invitation --json
+hpl version
 ```
+
+---
+
+## JSON Output Contract
+
+Structured output is treated as a **contract**, not a courtesy.
+
+When `--json` is provided:
+
+- stdout contains **only valid JSON**
+- stderr is used for logs and diagnostics
+- exit codes are deterministic
+
+A verification step is included:
+
+```bash
+npm run json:check
+```
+
+This command fails if any non-JSON output appears on stdout.
+
+---
+
+## What HPL Is Not
+
+HPL is not:
+- a chatbot interface
+- an agent framework
+- a memory system
+- an inference layer
+
+It is a command-line tool for interacting with Human Pattern Lab systems in a predictable, human-owned way.
+
+---
+
+**The Human Pattern Lab**  
+https://thehumanpatternlab.com
+
+*The lantern is lit.  
+The foxes are watching.*

package/dist/bin/hpl.js

@@ -2,157 +2,32 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — CLI ENTRYPOINT
    -----------------------------------------------------------
-   Commands:
-     - version
-     - capabilities
-     - health
-     - notes list
-     - notes get <slug>
-   Contract: --json => JSON only on stdout
+   Purpose:
+     - Register top-level commands
+     - Define global flags (--json)
+     - Parse argv
+   Contract:
+     --json => JSON only on stdout (enforced in command handlers)
    Notes:
-     - Avoid process.exit() inside command handlers (can trip libuv on Windows + tsx).
+     Avoid process.exit() inside handlers (Windows + tsx stability).
    =========================================================== */
 import { Command } from "commander";
-import { writeHuman, writeJson } from "../src/io";
-import { EXIT } from "../src/contract/exitCodes";
-import { runVersion } from "../src/commands/version";
-import { runCapabilities } from "../src/commands/capabilities";
-import { runHealth } from "../src/commands/health";
-import { runNotesList } from "../src/commands/notes/list";
-import { runNotesGet } from "../src/commands/notes/get";
-import { renderTable } from "../src/render/table";
-import { formatTags, safeLine, stripHtml } from "../src/render/text";
+import { versionCommand } from "../src/commands/version.js";
+import { capabilitiesCommand } from "../src/commands/capabilities.js";
+import { healthCommand } from "../src/commands/health.js";
+import { notesCommand } from "../src/commands/notes/notes.js";
+import { EXIT } from "../src/contract/exitCodes.js";
 const program = new Command();
 program
     .name("hpl")
     .description("Human Pattern Lab CLI (alpha)")
     .option("--json", "Emit contract JSON only on stdout")
-    .showHelpAfterError();
-function setExit(code) {
-    // Let Node exit naturally (important for Windows + tsx stability).
-    process.exitCode = code;
-}
-program
-    .command("version")
-    .description("Show CLI version (contract: show_version)")
-    .action(() => {
-    const opts = program.opts();
-    const envelope = runVersion("version");
-    if (opts.json)
-        writeJson(envelope);
-    else
-        writeHuman(`${envelope.data.name} ${envelope.data.version}`);
-    setExit(EXIT.OK);
-});
-program
-    .command("capabilities")
-    .description("Show CLI capabilities for agents (contract: show_capabilities)")
-    .action(() => {
-    const opts = program.opts();
-    const envelope = runCapabilities("capabilities");
-    if (opts.json)
-        writeJson(envelope);
-    else {
-        writeHuman(`intentTier: ${envelope.data.intentTier}`);
-        writeHuman(`schemaVersions: ${envelope.data.schemaVersions.join(", ")}`);
-        writeHuman(`supportedIntents:`);
-        for (const i of envelope.data.supportedIntents)
-            writeHuman(`  - ${i}`);
-    }
-    setExit(EXIT.OK);
-});
-program
-    .command("health")
-    .description("Check API health (contract: check_health)")
-    .action(async () => {
-    const opts = program.opts();
-    const result = await runHealth("health");
-    if (opts.json) {
-        writeJson(result.envelope);
-    }
-    else {
-        if (result.envelope.status === "ok") {
-            const d = result.envelope.data;
-            const db = d.dbPath ? ` (db: ${d.dbPath})` : "";
-            writeHuman(`ok${db}`);
-        }
-        else {
-            const e = result.envelope.error;
-            writeHuman(`error: ${e.code} — ${e.message}`);
-        }
-    }
-    setExit(result.exitCode);
-});
-const notes = program.command("notes").description("Lab Notes commands");
-notes
-    .command("list")
-    .description("List lab notes (contract: render_lab_note)")
-    .option("--limit <n>", "Limit number of rows (client-side)", (v) => parseInt(v, 10))
-    .action(async (cmdOpts) => {
-    const opts = program.opts();
-    const result = await runNotesList("notes list");
-    if (opts.json) {
-        writeJson(result.envelope);
-        setExit(result.exitCode);
-        return;
-    }
-    if (result.envelope.status !== "ok") {
-        const e = result.envelope.error;
-        writeHuman(`error: ${e.code} — ${e.message}`);
-        setExit(result.exitCode);
-        return;
-    }
-    const data = result.envelope.data;
-    const rows = data.notes ?? [];
-    const limit = Number.isFinite(cmdOpts.limit) && cmdOpts.limit > 0 ? cmdOpts.limit : rows.length;
-    const slice = rows.slice(0, limit);
-    const table = renderTable(slice, [
-        { header: "slug", width: 28, value: (n) => safeLine(String(n.slug ?? "")) },
-        { header: "title", width: 34, value: (n) => safeLine(String(n.title ?? "")) },
-        { header: "status", width: 10, value: (n) => safeLine(String(n.status ?? "-")) },
-        { header: "dept", width: 8, value: (n) => safeLine(String(n.department_id ?? "-")) },
-        { header: "tags", width: 22, value: (n) => formatTags(n.tags) },
-    ]);
-    writeHuman(table);
-    writeHuman(`\ncount: ${data.count}`);
-    setExit(result.exitCode);
-});
-notes
-    .command("get")
-    .description("Get a lab note by slug (contract: render_lab_note)")
-    .argument("<slug>", "Lab Note slug")
-    .option("--raw", "Print raw contentHtml (no HTML stripping)")
-    .action(async (slug, cmdOpts) => {
-    const opts = program.opts();
-    const result = await runNotesGet(slug, "notes get");
-    if (opts.json) {
-        writeJson(result.envelope);
-        setExit(result.exitCode);
-        return;
-    }
-    if (result.envelope.status !== "ok") {
-        const e = result.envelope.error;
-        writeHuman(`error: ${e.code} — ${e.message}`);
-        setExit(result.exitCode);
-        return;
-    }
-    const n = result.envelope.data;
-    writeHuman(`# ${n.title}`);
-    writeHuman(`slug: ${n.slug}`);
-    if (n.status)
-        writeHuman(`status: ${n.status}`);
-    if (n.type)
-        writeHuman(`type: ${n.type}`);
-    if (n.department_id)
-        writeHuman(`department_id: ${n.department_id}`);
-    if (n.published)
-        writeHuman(`published: ${n.published}`);
-    if (Array.isArray(n.tags))
-        writeHuman(`tags: ${formatTags(n.tags)}`);
-    writeHuman("");
-    const body = cmdOpts.raw ? String(n.contentHtml ?? "") : stripHtml(String(n.contentHtml ?? ""));
-    writeHuman(body || "(no content)");
-    setExit(result.exitCode);
+    .showHelpAfterError()
+    .configureHelp({ helpWidth: 100 });
+program.addCommand(versionCommand());
+program.addCommand(capabilitiesCommand());
+program.addCommand(healthCommand());
+program.addCommand(notesCommand());
+program.parseAsync(process.argv).catch(() => {
+    process.exitCode = EXIT.UNKNOWN;
 });
-// Let commander handle errors; set exit code without hard exit.
-program.parseAsync(process.argv).catch(() => setExit(EXIT.UNKNOWN));

package/dist/src/commands/capabilities.js

@@ -1,9 +1,33 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: capabilities
    =========================================================== */
+import { Command } from "commander";
+import { writeHuman, writeJson } from "../io.js";
+import { EXIT } from "../contract/exitCodes.js";
 import { getAlphaIntent } from "../contract/intents";
 import { ok } from "../contract/envelope";
 import { getCapabilitiesAlpha } from "../contract/capabilities";
+export function capabilitiesCommand() {
+    return new Command("capabilities")
+        .description("Show CLI capabilities for agents (contract: show_capabilities)")
+        .action((...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const envelope = runCapabilities("capabilities");
+        if (rootOpts.json) {
+            writeJson(envelope);
+        }
+        else {
+            const d = envelope.data ?? {};
+            writeHuman(`intentTier: ${d.intentTier ?? "-"}`);
+            writeHuman(`schemaVersions: ${(d.schemaVersions ?? []).join(", ")}`);
+            writeHuman(`supportedIntents:`);
+            for (const i of d.supportedIntents ?? [])
+                writeHuman(`  - ${i}`);
+        }
+        process.exitCode = EXIT.OK;
+    });
+}
 export function runCapabilities(commandName = "capabilities") {
     const intent = getAlphaIntent("show_capabilities");
     return ok(commandName, intent, getCapabilitiesAlpha());

package/dist/src/commands/health.js

@@ -1,6 +1,8 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: health
    =========================================================== */
+import { Command } from "commander";
+import { writeHuman, writeJson } from "../io.js";
 import { z } from "zod";
 import { getAlphaIntent } from "../contract/intents";
 import { ok, err } from "../contract/envelope";
@@ -10,6 +12,30 @@ const HealthSchema = z.object({
     status: z.string(),
     dbPath: z.string().optional(),
 });
+export function healthCommand() {
+    return new Command("health")
+        .description("Check API health (contract: check_health)")
+        .action(async (...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const result = await runHealth("health");
+        if (rootOpts.json) {
+            writeJson(result.envelope);
+        }
+        else {
+            if (result.envelope.status === "ok") {
+                const d = result.envelope.data ?? {};
+                const db = d.dbPath ? ` (db: ${d.dbPath})` : "";
+                writeHuman(`ok${db}`);
+            }
+            else {
+                const e = result.envelope.error ?? {};
+                writeHuman(`error: ${e.code ?? "E_UNKNOWN"} — ${e.message ?? "unknown"}`);
+            }
+        }
+        process.exitCode = result.exitCode ?? EXIT.UNKNOWN;
+    });
+}
 export async function runHealth(commandName = "health") {
     const intent = getAlphaIntent("check_health");
     try {

package/dist/src/commands/notes/get.js

@@ -1,16 +1,35 @@
 /* ===========================================================
-   🌌 HUMAN PATTERN LAB — COMMAND: notes get <slug>
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
+   -----------------------------------------------------------
+   File: get.ts
+   Role: Notes subcommand: `hpl notes get <slug>`
+   Author: Ada (The Human Pattern Lab)
+   Assistant: Lyric
+   Lab Unit: SCMS — Systems & Code Management Suite
+   Status: Active
+   -----------------------------------------------------------
+   Design:
+     - Core function returns { envelope, exitCode }
+     - Commander adapter decides json vs human rendering
+     - Markdown is canonical (content_markdown)
    =========================================================== */
-import { getAlphaIntent } from "../../contract/intents";
-import { ok, err } from "../../contract/envelope";
-import { EXIT } from "../../contract/exitCodes";
-import { getJson, HttpError } from "../../http/client";
-import { LabNoteSchema } from "../../types/labNotes";
-export async function runNotesGet(slug, commandName = "notes get") {
+import { Command } from "commander";
+import { getOutputMode, printJson } from "../../cli/output.js";
+import { renderText } from "../../render/text.js";
+import { LabNoteDetailSchema } from "../../types/labNotes.js";
+import { getAlphaIntent } from "../../contract/intents.js";
+import { ok, err } from "../../contract/envelope.js";
+import { EXIT } from "../../contract/exitCodes.js";
+import { getJson, HttpError } from "../../http/client.js";
+/**
+ * Core: fetch a single published Lab Note (detail).
+ * Returns structured envelope + exitCode (no printing here).
+ */
+export async function runNotesGet(slug, commandName = "notes.get") {
     const intent = getAlphaIntent("render_lab_note");
     try {
         const payload = await getJson(`/lab-notes/${encodeURIComponent(slug)}`);
-        const parsed = LabNoteSchema.safeParse(payload);
+        const parsed = LabNoteDetailSchema.safeParse(payload);
         if (!parsed.success) {
             return {
                 envelope: err(commandName, intent, {
@@ -21,14 +40,16 @@ export async function runNotesGet(slug, commandName = "notes get") {
                 exitCode: EXIT.CONTRACT,
             };
         }
-        const note = parsed.data;
-        return { envelope: ok(commandName, intent, note), exitCode: EXIT.OK };
+        return { envelope: ok(commandName, intent, parsed.data), exitCode: EXIT.OK };
     }
     catch (e) {
         if (e instanceof HttpError) {
-            if (e.status == 404) {
+            if (e.status === 404) {
                 return {
-                    envelope: err(commandName, intent, { code: "E_NOT_FOUND", message: `No lab note found for slug: ${slug}` }),
+                    envelope: err(commandName, intent, {
+                        code: "E_NOT_FOUND",
+                        message: `No lab note found for slug: ${slug}`,
+                    }),
                     exitCode: EXIT.NOT_FOUND,
                 };
             }
@@ -46,3 +67,22 @@ export async function runNotesGet(slug, commandName = "notes get") {
         return { envelope: err(commandName, intent, { code: "E_UNKNOWN", message: msg }), exitCode: EXIT.UNKNOWN };
     }
 }
+/**
+ * Commander: `hpl notes get <slug>`
+ */
+export function notesGetSubcommand() {
+    return new Command("get")
+        .description("Get a Lab Note by slug (contract: render_lab_note)")
+        .argument("<slug>", "Lab Note slug")
+        .action(async (slug, opts, cmd) => {
+        const mode = getOutputMode(cmd);
+        const { envelope, exitCode } = await runNotesGet(slug, "notes.get");
+        if (mode === "json") {
+            printJson(envelope);
+        }
+        else {
+            renderText(envelope);
+        }
+        process.exitCode = exitCode;
+    });
+}

package/dist/src/commands/notes/list.js

@@ -1,16 +1,37 @@
 /* ===========================================================
-   🌌 HUMAN PATTERN LAB — COMMAND: notes list
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
+   -----------------------------------------------------------
+   File: list.ts
+   Role: Notes subcommand: `hpl notes list`
+   Author: Ada (The Human Pattern Lab)
+   Assistant: Lyric
+   Lab Unit: SCMS — Systems & Code Management Suite
+   Status: Active
+   -----------------------------------------------------------
+   Design:
+     - Core function returns { envelope, exitCode }
+     - Commander adapter decides json vs human rendering
+     - JSON mode emits stdout-only structured data
    =========================================================== */
-import { getAlphaIntent } from "../../contract/intents";
-import { ok, err } from "../../contract/envelope";
-import { EXIT } from "../../contract/exitCodes";
-import { getJson, HttpError } from "../../http/client";
-import { LabNoteListSchema } from "../../types/labNotes";
-export async function runNotesList(commandName = "notes list") {
+import { Command } from "commander";
+import { getOutputMode, printJson } from "../../cli/output.js";
+import { formatTags, renderTable, safeLine } from "../../render/table.js";
+import { renderText } from "../../render/text.js";
+import { LabNotePreviewListSchema } from "../../types/labNotes.js";
+import { getAlphaIntent } from "../../contract/intents.js";
+import { ok, err } from "../../contract/envelope.js";
+import { EXIT } from "../../contract/exitCodes.js";
+import { getJson, HttpError } from "../../http/client.js";
+/**
+ * Core: fetch the published lab note previews.
+ * Returns structured envelope + exitCode (no printing here).
+ */
+export async function runNotesList(commandName = "notes.list", locale) {
     const intent = getAlphaIntent("render_lab_note");
     try {
-        const payload = await getJson("/lab-notes");
-        const parsed = LabNoteListSchema.safeParse(payload);
+        const qp = locale ? `?locale=${encodeURIComponent(locale)}` : "";
+        const payload = await getJson(`/lab-notes${qp}`);
+        const parsed = LabNotePreviewListSchema.safeParse(payload);
         if (!parsed.success) {
             return {
                 envelope: err(commandName, intent, {
@@ -21,9 +42,7 @@ export async function runNotesList(commandName = "notes list") {
                 exitCode: EXIT.CONTRACT,
             };
         }
-        // Deterministic: preserve API order, but ensure stable array type.
-        const notes = parsed.data;
-        return { envelope: ok(commandName, intent, { count: notes.length, notes }), exitCode: EXIT.OK };
+        return { envelope: ok(commandName, intent, parsed.data), exitCode: EXIT.OK };
     }
     catch (e) {
         if (e instanceof HttpError) {
@@ -41,3 +60,40 @@ export async function runNotesList(commandName = "notes list") {
         return { envelope: err(commandName, intent, { code: "E_UNKNOWN", message: msg }), exitCode: EXIT.UNKNOWN };
     }
 }
+/* ----------------------------------------
+   Helper: human table renderer for notes
+----------------------------------------- */
+function renderNotesListTable(envelope) {
+    const rows = Array.isArray(envelope?.data) ? envelope.data : [];
+    const cols = [
+        { header: "Title", width: 32, value: (r) => safeLine(r?.title ?? "-") },
+        { header: "Slug", width: 26, value: (r) => safeLine(r?.slug ?? "-") },
+        { header: "Locale", width: 6, value: (r) => safeLine(r?.locale ?? "-") },
+        { header: "Type", width: 8, value: (r) => safeLine(r?.type ?? "-") },
+        { header: "Tags", width: 24, value: (r) => formatTags(r?.tags) },
+    ];
+    console.log(renderTable(rows, cols));
+}
+/* ----------------------------------------
+   Subcommand builder
+----------------------------------------- */
+export function notesListSubcommand() {
+    return new Command("list")
+        .description("List published Lab Notes (contract: render_lab_note)")
+        .action(async (opts, cmd) => {
+        const mode = getOutputMode(cmd);
+        const { envelope, exitCode } = await runNotesList("notes.list", opts.locale);
+        if (mode === "json") {
+            printJson(envelope);
+        }
+        else {
+            try {
+                renderNotesListTable(envelope);
+            }
+            catch {
+                renderText(envelope);
+            }
+        }
+        process.exitCode = exitCode;
+    });
+}

package/dist/src/commands/notes/notes.js

@@ -0,0 +1,32 @@
+/* ===========================================================
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
+   -----------------------------------------------------------
+   File: notes.ts
+   Role: Notes command assembler (domain root)
+   Author: Ada (The Human Pattern Lab)
+   Assistant: Lyric
+   Lab Unit: SCMS — Systems & Code Management Suite
+   Status: Active
+   -----------------------------------------------------------
+   Purpose:
+     Defines the `hpl notes` command tree and mounts subcommands:
+       - hpl notes list
+       - hpl notes get <slug>
+       - hpl notes sync
+   -----------------------------------------------------------
+   Design:
+     - This file is wiring only (no network calls, no rendering)
+     - Subcommands own their own output logic and contracts
+   =========================================================== */
+import { Command } from "commander";
+import { notesListSubcommand } from "./list.js";
+import { notesGetSubcommand } from "./get.js";
+import { notesSyncSubcommand } from "./notesSync.js";
+export function notesCommand() {
+    const notes = new Command("notes").description("Lab Notes commands");
+    // Subcommands
+    notes.addCommand(notesListSubcommand());
+    notes.addCommand(notesGetSubcommand());
+    notes.addCommand(notesSyncSubcommand());
+    return notes;
+}

package/dist/src/commands/notes/notesSync.js

@@ -0,0 +1,221 @@
+/* ===========================================================
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
+   -----------------------------------------------------------
+   File: notesSync.ts
+   Role: Notes subcommand: `hpl notes sync`
+   Author: Ada (The Human Pattern Lab)
+   Assistant: Lyric
+   Lab Unit: SCMS — Systems & Code Management Suite
+   Status: Active
+   -----------------------------------------------------------
+   Purpose:
+     Sync local markdown Lab Notes to the Lab API with predictable
+     behavior in both human and automation contexts.
+
+     Supports content-ledger workflows via --content-repo (clones
+     the content repo locally, then syncs from it).
+   -----------------------------------------------------------
+   Key Behaviors:
+     - Human mode: readable progress + summaries
+     - JSON mode (--json): stdout emits ONLY valid JSON (contract)
+     - Errors: stderr only
+     - Exit codes: deterministic (non-zero only on failure)
+   =========================================================== */
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { HPL_BASE_URL, HPL_TOKEN } from "../../lib/config.js";
+import { httpJson } from "../../lib/http.js";
+import { listMarkdownFiles, readNote } from "../../lib/notes.js";
+import { getOutputMode, printJson } from "../../cli/output.js";
+import { buildSyncReport } from "../../cli/outputContract.js";
+import { resolveContentRepo } from "../../lib/contentRepo.js";
+import { LabNoteUpsertSchema } from "../../types/labNotes.js";
+async function upsertNote(baseUrl, token, note, locale) {
+    const payload = {
+        slug: note.slug,
+        title: note.attributes.title,
+        markdown: note.markdown,
+        locale,
+        // Optional fields if your note parser provides them
+        subtitle: note.attributes.subtitle,
+        summary: note.attributes.summary,
+        tags: note.attributes.tags,
+        published: note.attributes.published,
+        status: note.attributes.status,
+        type: note.attributes.type,
+        dept: note.attributes.dept,
+    };
+    const parsed = LabNoteUpsertSchema.safeParse(payload);
+    if (!parsed.success) {
+        throw new Error(`Invalid LabNoteUpsertPayload: ${parsed.error.message}`);
+    }
+    return httpJson({ baseUrl, token }, "POST", "/lab-notes/upsert", parsed.data);
+}
+/**
+ * Commander: `hpl notes sync`
+ */
+export function notesSyncSubcommand() {
+    return new Command("sync")
+        .description("Sync markdown notes to the API")
+        // IMPORTANT: do NOT default --dir here (it conflicts with repo-first flows)
+        .option("--dir <path>", "Directory containing markdown notes")
+        .option("--content-repo <repo>", "GitHub owner/name or URL for Lab Notes content repo (or HPL_CONTENT_REPO env)")
+        .option("--content-ref <ref>", "Branch, tag, or SHA to checkout (default: main)")
+        .option("--content-subdir <path>", "Subdirectory inside repo containing labnotes (default: labnotes)")
+        .option("--cache-dir <path>", "Local cache directory for cloned content repos")
+        .option("--locale <code>", "Locale code", "en")
+        .option("--base-url <url>", "Override API base URL (ex: https://api.thehumanpatternlab.com)")
+        .option("--dry-run", "Print what would be sent, but do not call the API", false)
+        .option("--only <slug>", "Sync only a single note by slug")
+        .option("--limit <n>", "Sync only the first N notes", (v) => parseInt(v, 10))
+        .action(async (opts, cmd) => {
+        const mode = getOutputMode(cmd); // "json" | "human"
+        const jsonError = (message, extra) => {
+            if (mode === "json") {
+                process.stderr.write(JSON.stringify({ ok: false, error: { message, extra } }, null, 2) + "\n");
+            }
+            else {
+                console.error(message);
+                if (extra)
+                    console.error(extra);
+            }
+            process.exitCode = 1;
+        };
+        // -----------------------------
+        // Resolve content source → rootDir
+        // -----------------------------
+        const envRepo = String(process.env.SKULK_CONTENT_REPO ?? "").trim();
+        const repoArg = String(opts.contentRepo ?? "").trim() || envRepo;
+        const dirRaw = String(opts.dir ?? "").trim();
+        const dirArg = dirRaw || (!repoArg ? "./src/labnotes/en" : "");
+        const ref = String(opts.contentRef ?? "main").trim() || "main";
+        const subdir = String(opts.contentSubdir ?? "labnotes").trim() || "labnotes";
+        const cacheDir = String(opts.cacheDir ?? "").trim() || undefined;
+        if (dirArg && repoArg) {
+            jsonError("Use only one content source: either --dir OR --content-repo (or SKULK_CONTENT_REPO), not both.", { dir: dirArg, contentRepo: repoArg });
+            return;
+        }
+        let rootDir;
+        let source;
+        try {
+            if (repoArg) {
+                const resolved = await resolveContentRepo({
+                    repo: repoArg,
+                    ref,
+                    cacheDir,
+                    quietStdout: mode === "json", // keep stdout clean for JSON mode
+                });
+                rootDir = path.join(resolved.dir, subdir);
+                source = { kind: "repo", repo: repoArg, ref, subdir, dir: rootDir };
+            }
+            else {
+                rootDir = dirArg;
+                source = { kind: "dir", dir: rootDir };
+            }
+        }
+        catch (e) {
+            jsonError("Failed to resolve content source.", {
+                error: String(e),
+                repo: repoArg || undefined,
+                dir: dirArg || undefined,
+            });
+            return;
+        }
+        if (!fs.existsSync(rootDir)) {
+            jsonError(`Notes directory not found: ${rootDir}`, {
+                hintRepo: "If using repo mode, verify the repo contains labnotes/<locale>/",
+                hintDir: `Try: hpl notes sync --dir "..\\\\the-human-pattern-lab\\\\src\\\\labnotes\\\\en"`,
+                source,
+            });
+            return;
+        }
+        // -----------------------------
+        // Continue with existing sync flow
+        // -----------------------------
+        const baseUrl = HPL_BASE_URL(opts.baseUrl);
+        const token = HPL_TOKEN();
+        const files = listMarkdownFiles(rootDir);
+        let selectedFiles = files;
+        if (opts.only) {
+            selectedFiles = files.filter((f) => f.toLowerCase().includes(String(opts.only).toLowerCase()));
+        }
+        if (opts.limit && Number.isFinite(opts.limit)) {
+            selectedFiles = selectedFiles.slice(0, opts.limit);
+        }
+        if (selectedFiles.length === 0) {
+            if (mode === "json") {
+                printJson({
+                    ok: true,
+                    action: "noop",
+                    message: "No matching notes found.",
+                    matched: 0,
+                    source,
+                });
+            }
+            else {
+                console.log("No matching notes found.");
+            }
+            process.exitCode = 0;
+            return;
+        }
+        if (mode === "human") {
+            console.log(`HPL syncing ${selectedFiles.length} note(s) from ${rootDir}`);
+            if (source.kind === "repo") {
+                console.log(`Content Repo: ${source.repo} @ ${source.ref} (${source.subdir})`);
+            }
+            console.log(`API: ${baseUrl}`);
+            console.log(`Locale: ${opts.locale}`);
+            console.log(opts.dryRun ? "Mode: DRY RUN (no writes)" : "Mode: LIVE (writing)");
+        }
+        const results = [];
+        for (const file of selectedFiles) {
+            try {
+                const note = readNote(file, opts.locale);
+                if (opts.dryRun) {
+                    results.push({ file, slug: note.slug, status: "dry-run" });
+                    if (mode === "human") {
+                        console.log(`\n---\n${note.slug}\n${file}\nfrontmatter keys: ${Object.keys(note.attributes).join(", ")}`);
+                    }
+                    continue;
+                }
+                const res = await upsertNote(baseUrl, token, note, opts.locale);
+                results.push({ file, slug: note.slug, status: "ok", action: res.action });
+                if (mode === "human") {
+                    console.log(`✅ ${note.slug} (${res.action ?? "ok"})`);
+                }
+            }
+            catch (e) {
+                const msg = String(e);
+                results.push({ file, status: "fail", error: msg });
+                if (mode === "human") {
+                    console.error(`❌ ${file}`);
+                    console.error(msg);
+                }
+            }
+        }
+        const report = buildSyncReport({
+            results,
+            dryRun: Boolean(opts.dryRun),
+            locale: opts.locale,
+            baseUrl,
+        });
+        if (mode === "json") {
+            // Attach source without rewriting your contract builder (minimal + safe).
+            printJson({ ...report, source });
+            if (!report.ok)
+                process.exitCode = 1;
+        }
+        else {
+            const { synced, dryRun, failed } = report.summary;
+            if (report.dryRun) {
+                console.log(`\nDone. ${dryRun} note(s) would be synced (dry-run). Failures: ${failed}`);
+            }
+            else {
+                console.log(`\nDone. ${synced} note(s) synced successfully. Failures: ${failed}`);
+            }
+            if (!report.ok)
+                process.exitCode = 1;
+        }
+    });
+}

package/dist/src/commands/notesSync.js

@@ -58,7 +58,7 @@ export function notesSyncCommand() {
         .option('--dir <path>', 'Directory containing markdown notes', './src/labnotes/en')
         //.option("--dir <path>", "Directory containing markdown notes", "./labnotes/en")
         .option('--locale <code>', 'Locale code', 'en')
-        .option('--base-url <url>', 'Override API base URL (ex: https://thehumanpatternlab.com/api)')
+        .option('--base-url <url>', 'Override API base URL (ex: https://api.thehumanpatternlab.com)')
         .option('--dry-run', 'Print what would be sent, but do not call the API', false)
         .option('--only <slug>', 'Sync only a single note by slug')
         .option('--limit <n>', 'Sync only the first N notes', (v) => parseInt(v, 10))

package/dist/src/commands/version.js

@@ -1,11 +1,28 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: version
    =========================================================== */
+import { Command } from "commander";
+import { writeHuman, writeJson } from "../io.js";
+import { EXIT } from "../contract/exitCodes.js";
 import { createRequire } from "node:module";
 import { getAlphaIntent } from "../contract/intents";
 import { ok } from "../contract/envelope";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
+export function versionCommand() {
+    return new Command("version")
+        .description("Show CLI version (contract: show_version)")
+        .action((...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const envelope = runVersion("version");
+        if (rootOpts.json)
+            writeJson(envelope);
+        else
+            writeHuman(`${envelope.data?.name} ${envelope.data?.version}`.trim());
+        process.exitCode = EXIT.OK;
+    });
+}
 export function runVersion(commandName = "version") {
     const intent = getAlphaIntent("show_version");
     return ok(commandName, intent, { name: pkg.name, version: pkg.version });

package/dist/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /* ===========================================================
-   🦊 THE HUMAN PATTERN LAB — SKULK CLI
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
    -----------------------------------------------------------
    File: notesSync.ts
    Role: Command Implementation
@@ -8,7 +8,7 @@
    Assistant: Lyric
    Status: Active
    Description:
-     Implements the `skulk notes sync` command.
+     Implements the `hpl notes sync` command.
      Handles human-readable and machine-readable output modes
      with enforced JSON purity for automation safety.
    -----------------------------------------------------------
@@ -19,18 +19,19 @@
      - Exit codes are deterministic
    =========================================================== */
 import { Command } from "commander";
-import { notesSyncCommand } from "./commands/notesSync.js";
+import { notesSyncSubcommand } from "./commands/notes/notesSync.js";
 const program = new Command();
 program
-    .name("skulk")
-    .description("Skulk CLI for The Human Pattern Lab")
+    .name("hpl")
+    .description("Human Pattern Lab CLI (alpha)")
     .version("0.1.0")
-    .option("--json", "Output machine-readable JSON")
+    .option("--json", "Emit contract JSON only on stdout")
     .configureHelp({ helpWidth: 100 });
 const argv = process.argv.slice(2);
 if (argv.length === 0) {
     program.outputHelp();
     process.exit(0);
 }
-program.addCommand(notesSyncCommand());
+// Mount domains
+program.addCommand(notesSyncSubcommand());
 program.parse(process.argv);

package/dist/src/lib/config.js

@@ -3,15 +3,15 @@ import path from 'node:path';
 import os from 'node:os';
 import { z } from 'zod';
 /**
- * Skulk CLI configuration schema
- * Stored in ~/.humanpatternlab/skulk.json
+ * HPL CLI configuration schema
+ * Stored in ~/.humanpatternlab/hpl.json
  */
 const ConfigSchema = z.object({
-    apiBaseUrl: z.string().url().default('https://thehumanpatternlab.com/api'),
+    apiBaseUrl: z.string().url().default('https://api.thehumanpatternlab.com'),
     token: z.string().optional(),
 });
 function getConfigPath() {
-    return path.join(os.homedir(), '.humanpatternlab', 'skulk.json');
+    return path.join(os.homedir(), '.humanpatternlab', 'hpl.json');
 }
 export function loadConfig() {
     const p = getConfigPath();
@@ -28,11 +28,11 @@ export function saveConfig(partial) {
     const next = ConfigSchema.parse({ ...current, ...partial });
     fs.writeFileSync(p, JSON.stringify(next, null, 2), 'utf-8');
 }
-export function SKULK_BASE_URL(override) {
+export function HPL_BASE_URL(override) {
     if (override?.trim())
         return override.trim();
     // NEW official env var
-    const env = process.env.SKULK_BASE_URL?.trim();
+    const env = process.env.HPL_BASE_URL?.trim();
     if (env)
         return env;
     // optional legacy support (remove later if you want)
@@ -41,8 +41,8 @@ export function SKULK_BASE_URL(override) {
         return legacy;
     return loadConfig().apiBaseUrl;
 }
-export function SKULK_TOKEN() {
-    const env = process.env.SKULK_TOKEN?.trim();
+export function HPL_TOKEN() {
+    const env = process.env.HPL_TOKEN?.trim();
     if (env)
         return env;
     const legacy = process.env.HPL_TOKEN?.trim();

package/dist/src/lib/contentRepo.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execa } from "execa";
+function normalizeRepoUrl(repo) {
+    const raw = repo.trim();
+    if (raw.startsWith("http://") || raw.startsWith("https://") || raw.startsWith("git@"))
+        return raw;
+    return `https://github.com/${raw}.git`;
+}
+function safeRepoKey(repo) {
+    // stable-ish folder name for owner/name or URL
+    return repo.trim().replace(/[^a-z0-9._-]+/gi, "_").toLowerCase();
+}
+function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+async function runGit(args, opts = {}) {
+    const p = execa("git", args, {
+        cwd: opts.cwd,
+        // Avoid stdout pollution when in --json mode (or any strict mode).
+        stdio: opts.quietStdout ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (opts.quietStdout) {
+        p.stdout?.on("data", (d) => process.stderr.write(d));
+        p.stderr?.on("data", (d) => process.stderr.write(d));
+    }
+    return await p;
+}
+export async function resolveContentRepo({ repo, ref = "main", cacheDir, quietStdout = false, }) {
+    const repoUrl = normalizeRepoUrl(repo);
+    const base = cacheDir ?? path.join(os.homedir(), ".hpl", "cache", "content");
+    const dir = path.join(base, safeRepoKey(repo));
+    ensureDir(base);
+    const gitDir = path.join(dir, ".git");
+    const exists = fs.existsSync(gitDir);
+    if (!exists) {
+        ensureDir(dir);
+        // Clone shallow if branch-like ref; if ref is a sha, shallow clone won’t help much.
+        await runGit(["clone", "--depth", "1", "--branch", ref, repoUrl, dir], { quietStdout });
+    }
+    else {
+        // Keep it predictable: fetch + checkout + ff-only pull.
+        await runGit(["-C", dir, "fetch", "--all", "--tags", "--prune"], { quietStdout });
+        await runGit(["-C", dir, "checkout", ref], { quietStdout });
+        await runGit(["-C", dir, "pull", "--ff-only"], { quietStdout });
+    }
+    return { dir, repoUrl, ref };
+}

package/dist/src/render/table.js

@@ -3,6 +3,13 @@
    -----------------------------------------------------------
    Purpose: Deterministic fixed-width table output.
    =========================================================== */
+export function safeLine(s) {
+    return (s ?? "").replace(/\s+/g, " ").trim();
+}
+export function formatTags(tags) {
+    const t = (tags ?? []).filter(Boolean);
+    return t.length ? t.join(", ") : "-";
+}
 function pad(s, width) {
     const str = (s ?? "").toString();
     if (str.length >= width)

package/dist/src/render/text.js

@@ -1,8 +1,4 @@
-/* ===========================================================
-   🌌 HUMAN PATTERN LAB — TEXT RENDER UTILS
-   -----------------------------------------------------------
-   Purpose: Deterministic, dependency-free formatting for terminals.
-   =========================================================== */
+import { formatTags, safeLine } from "./table";
 export function stripHtml(input) {
     const s = (input || "");
     // Convert common structure to deterministic newlines first
@@ -31,10 +27,72 @@ export function stripHtml(input) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
-export function safeLine(s) {
-    return (s ?? "").replace(/\s+/g, " ").trim();
+function renderError(env) {
+    console.error(`✖ ${env.command}`);
+    if (env.error?.message) {
+        console.error(safeLine(env.error.message));
+    }
+    if (env.error?.details) {
+        console.error();
+        console.error(stripHtml(String(env.error.details)));
+    }
 }
-export function formatTags(tags) {
-    const t = (tags ?? []).filter(Boolean);
-    return t.length ? t.join(", ") : "-";
+function renderWarn(env) {
+    console.log(`⚠ ${env.command}`);
+    for (const w of env.warnings ?? []) {
+        console.log(`- ${safeLine(w)}`);
+    }
+    if (env.data !== undefined) {
+        console.log();
+        renderData(env.data);
+    }
+}
+function renderSuccess(env) {
+    renderData(env.data);
+}
+function renderData(data) {
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            renderItem(item);
+            console.log();
+        }
+        return;
+    }
+    if (typeof data === "object" && data !== null) {
+        renderItem(data);
+        return;
+    }
+    console.log(String(data));
+}
+function renderItem(note) {
+    if (note.title) {
+        console.log(safeLine(note.title));
+    }
+    if (note.subtitle) {
+        console.log(`  ${safeLine(note.subtitle)}`);
+    }
+    if (note.summary || note.excerpt) {
+        console.log();
+        console.log(stripHtml(note.summary ?? note.excerpt));
+    }
+    if (note.tags) {
+        console.log();
+        console.log(`Tags: ${formatTags(note.tags)}`);
+    }
+}
+export function renderText(envelope) {
+    switch (envelope.status) {
+        case "error":
+            renderError(envelope);
+            return;
+        case "warn":
+            renderWarn(envelope);
+            return;
+        case "ok":
+            renderSuccess(envelope);
+            return;
+        default:
+            // Exhaustiveness guard
+            console.error("Unknown envelope status");
+    }
 }

package/dist/src/types/labNotes.js

@@ -5,23 +5,107 @@
    Notes:
      - Keep permissive: API may add fields (additive).
    =========================================================== */
+// - GET /lab-notes         -> LabNotePreview[]
+// - GET /lab-notes/:slug   -> LabNoteDetail (LabNoteView + content_markdown)
 import { z } from "zod";
-export const LabNoteSchema = z.object({
+/** Mirrors API LabNoteType */
+export const LabNoteTypeSchema = z.enum(["labnote", "paper", "memo", "lore", "weather"]);
+/** Mirrors API LabNoteStatus */
+export const LabNoteStatusSchema = z.enum(["published", "draft", "archived"]);
+export const ALLOWED_NOTE_TYPES = new Set([
+    "labnote",
+    "paper",
+    "memo",
+    "lore",
+    "weather",
+]);
+/**
+ * GET /lab-notes (list)
+ * You are selecting from v_lab_notes without content_html/markdown,
+ * then mapping via mapToLabNotePreview(...).
+ *
+ * We infer likely fields from the SELECT + typical preview mapper.
+ * Keep passthrough to allow additive changes.
+ */
+export const LabNotePreviewSchema = z
+    .object({
     id: z.string(),
     slug: z.string(),
     title: z.string(),
-    summary: z.string().optional().default(""),
-    contentHtml: z.string().optional().default(""),
-    published: z.string().optional().nullable(),
-    status: z.string().optional(),
-    type: z.string().optional(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    excerpt: z.string().optional(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
     locale: z.string().optional(),
-    department_id: z.string().optional(),
+    department_id: z.string().optional(), // DB has it; mapper may include it
     shadow_density: z.number().optional(),
-    safer_landing: z.boolean().optional(),
-    tags: z.array(z.string()).optional().default([]),
-    readingTime: z.number().optional(),
+    safer_landing: z.boolean().optional(), // DB is number-ish; mapper likely coerces
+    readingTime: z.number().optional(), // from read_time_minutes
+    published: z.string().optional(), // from published_at (if mapper emits it)
     created_at: z.string().optional(),
     updated_at: z.string().optional(),
-}).passthrough();
-export const LabNoteListSchema = z.array(LabNoteSchema);
+    tags: z.array(z.string()).optional(), // mapper adds tags
+})
+    .passthrough();
+export const LabNotePreviewListSchema = z.array(LabNotePreviewSchema);
+/**
+ * API LabNoteView shape (detail rendering fields).
+ * This aligns to your LabNoteView interface.
+ */
+export const LabNoteViewSchema = z
+    .object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    // NOTE: contentHtml intentionally excluded.
+    // Markdown is the canonical source of truth for CLI clients.
+    published: z.string(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
+    locale: z.string().optional(),
+    author: z
+        .object({
+        kind: z.enum(["human", "ai", "hybrid"]),
+        name: z.string().optional(),
+        id: z.string().optional(),
+    })
+        .optional(),
+    department_id: z.string(),
+    shadow_density: z.number(),
+    safer_landing: z.boolean(),
+    tags: z.array(z.string()),
+    readingTime: z.number(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+})
+    .passthrough();
+/**
+ * GET /lab-notes/:slug returns LabNoteView + content_markdown (canonical truth).
+ */
+export const LabNoteDetailSchema = LabNoteViewSchema.extend({
+    content_markdown: z.string().optional(), // API always includes it in your code, but keep optional for safety
+});
+/**
+ * CLI → API payload for upsert (notes sync).
+ * Strict: our outbound contract.
+ */
+export const LabNoteUpsertSchema = z
+    .object({
+    slug: z.string().min(1),
+    title: z.string().min(1),
+    markdown: z.string().min(1),
+    locale: z.string().optional(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    published: z.string().optional(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
+})
+    .strict();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehumanpatternlab/hpl",
-  "version": "0.0.1-alpha.5",
+  "version": "0.0.1-alpha.6",
   "description": "AI-forward, automation-safe SDK and CLI for the Human Pattern Lab",
   "type": "module",
   "license": "MIT",
@@ -37,10 +37,12 @@
     "start": "node ./dist/bin/hpl.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "json:check": "tsx ./bin/hpl.ts --json version | node -e \"JSON.parse(require('fs').readFileSync(0,'utf8'))\"",
     "lint": "node -e \"console.log('lint: add eslint when ready')\""
   },
   "dependencies": {
     "commander": "^12.1.0",
+    "execa": "^9.6.1",
     "gray-matter": "^4.0.3",
     "zod": "^3.24.1"
   },