CORE [SCMS] establish contract-first HPL CLI read surface for Lab Notes 🧬

.github/RELEASE_TEMPLATE.md

@@ -0,0 +1,130 @@
+# HPL CLI v{{version}}
+
+> Contract-first CLI release for **The Human Pattern Lab**  
+> This release follows the same change classification and discipline as the Lab API.
+
+---
+
+## 🔎 Summary
+
+Brief, high-signal description of what this CLI release delivers and **why it exists**.
+
+Example:  
+This release introduces the first contract-stable CLI interface for reading Lab Notes from the ledger-backed API, with explicit intent metadata and machine-parseable output.
+
+---
+
+## 📦 Compatibility
+
+| Component | Version |
+|---------|--------|
+| **CLI package** | `{{version}}` |
+| **CLI schemaVersion** | `{{schemaVersion}}` |
+| **Compatible API versions** | `>= {{apiVersion}}` |
+
+Compatibility is defined by the **CLI contract**, not by implementation details.
+
+---
+
+## 🚨 Breaking Changes
+
+> Only include this section if applicable.
+
+- Describe **what changed**
+- Describe **why it changed**
+- Describe **what users or agents must do**
+
+Example:
+- CLI JSON output for `notes list` now nests results under `data.notes`  
+  (previously returned a top-level array)
+
+Breaking changes **always** imply:
+- CLI `schemaVersion` bump
+- Explicit callout here
+- Compatibility table update
+
+---
+
+## ➕ Additive Changes
+
+New functionality that does **not** break existing usage.
+
+Example:
+- Added `notes get <slug>` command
+- Added `--limit` flag to `notes list`
+- Added intent metadata to all JSON outputs
+
+Additive changes may bump the CLI package version, but **do not require** a contract bump.
+
+---
+
+## 🔧 Internal Changes
+
+Refactors, fixes, or improvements that do not affect external behavior.
+
+Example:
+- Refactored HTTP client to support raw and enveloped API responses
+- Improved Windows stability by removing hard process exits
+- Internal rendering utilities for deterministic terminal output
+
+---
+
+## 🧠 Contract Notes
+
+This release maintains the following guarantees:
+
+- All `--json` output conforms to `schemaVersion: {{schemaVersion}}`
+- Intent identifiers are stable and unchanged
+- Exit code meanings are unchanged
+
+If this release introduces new intents, they are **additive** and documented below.
+
+---
+
+## 🎯 Supported Intents (Alpha Tier)
+
+```
+show_version
+show_capabilities
+check_health
+render_lab_note
+```
+
+Intent semantics are unchanged unless explicitly stated.
+
+---
+
+## 🧪 Validation
+
+Recommended verification steps:
+
+```bash
+hpl version --json
+hpl capabilities --json
+hpl health --json
+hpl notes list --json
+hpl notes get <slug> --json
+```
+
+Successful execution confirms contract compatibility.
+
+---
+
+## 📚 Notes
+
+- This CLI release aligns with the **Lab API release discipline**
+- v0.x does not imply instability — it implies **explicit governance**
+- Humans are a tolerated interface
+
+---
+
+## 🔗 References
+
+- API Release: `{{apiReleaseLink}}`
+- CLI Contract: `schemaVersion {{schemaVersion}}`
+- Documentation: https://thehumanpatternlab.com/docs
+
+---
+
+🦊  
+*The foxes are watching. The contract holds.*

README.md

@@ -1,114 +1,35 @@
-<!--
-  Skulk CLI
-  The Human Pattern Lab
+# HPL CLI (Alpha) 🧭🦊
 
-  This README is written for humans.
-  Design rationale lives in DESIGN.md.
--->
-# Skulk CLI
+Contract-first CLI for The Human Pattern Lab.
 
-[![AI-Forward CLI](https://img.shields.io/badge/AI--Forward%20CLI-automation--safe%20by%20design-7c3aed?style=flat-square)](./DESIGN.md) ![Carmel Judgment](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg) ![npm](https://img.shields.io/npm/v/@thehumanpatternlab/skulk)
-
-
-> A modern, automation-safe CLI for The Human Pattern Lab.
-
-Skulk is a command-line tool for syncing and managing Lab Notes — built to work just as well for humans at the keyboard as it does for automation, CI, and agent-driven workflows.
-
----
-## What Skulk Connects To
-
-Skulk is the CLI for **The Human Pattern Lab API**.
-
-By default it 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.
-
----
-## Configuration
-
-### Environment variables
-
-- `SKULK_TOKEN` — API token used to authenticate requests.
-- `SKULK_BASE_URL` — Base URL for a Human Pattern Lab API instance (overridden by `--base-url`).
-
-Example:
-
-```bash
-export SKULK_TOKEN="..."
-export SKULK_BASE_URL="https://thehumanpatternlab.com/api"
-skulk notes sync --dir ./src/labnotes/en
-```
----
-
-## Why Skulk Exists
-
-Command-line tools no longer live in a human-only world.
-
-They’re run by:
-- developers exploring and iterating
-- scripts and CI pipelines
-- automation layers and AI-assisted workflows
-
-Skulk was designed from the start to behave **predictably and honestly** in all of those contexts — without sacrificing human usability.
-
----
-
-## 🤖 AI-Forward (for Humans)
-
-Skulk follows **AI-forward engineering principles** — not for AIs, but for the people who build tools that increasingly interact with them.
-
-### Dual Output Modes
-
-By default, Skulk is human-readable:
+## Install (local dev)
 
 ```bash
-skulk notes sync
+npm install
+npm run dev -- --help
 ```
 
-When `--json` is enabled:
-
-```bash
-skulk --json notes sync
-```
+## Config
 
-Skulk switches to machine-readable output:
-- stdout contains **only valid JSON**
-- no banners, emojis, or progress chatter
-- errors go to stderr
-- exit codes are deterministic
+- `HPL_API_BASE_URL` (default: `https://api.thehumanpatternlab.com`)
 
-This makes Skulk safe to use in:
-- scripts
-- CI pipelines
-- automation
-- AI-assisted workflows
+## Commands (MVP)
 
----
+- `hpl version`
+- `hpl capabilities`
+- `hpl health`
+- `hpl notes list [--limit N]`
+- `hpl notes get <slug> [--raw]`
 
-## JSON Output Contract
+## JSON contract
 
-Structured output is treated as a **contract**, not a courtesy.
+Add `--json` to emit machine-readable JSON only on stdout.
 
-The repository includes a built-in verification:
+### Examples
 
 ```bash
-npm run json:check
+hpl capabilities --json
+hpl health --json
+hpl notes list --json
+hpl notes get the-invitation --json
 ```
-
-This command runs Skulk in `--json` mode and fails immediately if *any* non-JSON output appears on stdout.
-
----
-
-## Design & Philosophy
-
-Curious why Skulk works this way?  
-→ [DESIGN.md](./DESIGN.md)
-
----
-
-## Philosophy
-
-> Automation shouldn’t require guessing what a tool *meant* to say.
-
-Skulk is boring in the best way:
-predictable, explicit, and dependable.