@headways/cli 0.4.1 → 1.0.0

package/README.md

@@ -1,9 +1,16 @@
 # @headways/cli
 
-The official CLI for [Headways](https://headways.ai) — author skills, sync them to your team, and capture workflows directly from Claude Code.
+The official CLI for [Headways](https://headways.ai). Two responsibilities:
+
+1. **Skill authoring** — talk to the backend API: scaffold, push drafts, list, submit feedback.
+2. **Claude Code runtime helpers** — small binaries that Claude Code hooks shell out to (`prime`, `emit`, `skill-run start`).
+
+Anything that mutates this machine's state — installing skill bundles, syncing the catalog, editing `~/.claude/settings.json` — lives in the [Headways desktop app](https://headways.ai/download) (macOS for now). The desktop auto-installs this CLI under `~/.local/bin/headways` on first launch.
 
 ## Installation
 
+The desktop app installs the CLI for you. For dev / local work:
+
 ```bash
 npm install -g @headways/cli
 ```
@@ -11,63 +18,66 @@ npm install -g @headways/cli
 ## Setup
 
 ```bash
-headways configure
-# Prompts for your API key (sk_…). Validates and saves org automatically.
+headways login
+# Browser SSO. Saves credentials + org to ~/.headways/config.json.
 ```
 
-Options:
-
 ```bash
-headways configure --token <key>              # non-interactive
-headways configure --api-url http://localhost:3001  # local dev
-headways configure status                    # show saved key + org
-headways configure clear                     # remove credentials
+headways config status                       # show saved token + org + URLs
+headways config clear                        # remove credentials
 ```
 
 ## Commands
 
-### Skills
+### Authoring
 
 ```bash
-headways skills new                          # scaffold a new skill interactively
+headways skills new                          # scaffold a new skill (creates ./<slug>/)
 headways skills new --slug <slug> --headline "<headline>"  # non-interactive
-headways skills import <path>               # ingest an existing file or directory
-headways skills push <slug>                 # sync local edits to the skill draft
-headways skills list                        # list skills in the active org
-headways skills capture                     # capture a workflow from Claude Code
+headways skills import <path>                # ingest an existing file or directory
+headways skills push <slug>                  # push local edits as a draft
+headways skills list                         # list skills in the active org
+headways skills feedback <slug>              # submit feedback on a skill
+headways skills guide                        # authoring reference (run before creating a skill)
 ```
 
-### Sync
+### Runtime helpers (invoked by Claude Code hooks; rarely run by hand)
 
 ```bash
-headways sync start                         # register device + pull updates once
-headways sync start --daemon                # poll every 60s for background updates
-headways sync status                        # show pending skill updates
-headways accept <skill>                     # install a pending update
+headways prime                               # print workflow context for AI agents
+headways emit --hook <namespace>.<name>      # emit a skill-run event
+headways skill-run start                     # create a run from a UserPromptSubmit hook
 ```
 
-### Other
+### Connections
 
 ```bash
-headways feedback <skillSlug>               # submit feedback on a skill run
-headways org use <slug>                     # switch active org
+headways connections list                    # list MCP connector authorizations
 ```
 
 ## Creating a skill from scratch
 
 ```bash
 cd ~/my-skills
-headways skills new                         # creates ./<slug>/ with SKILL.md,
-                                            # headways.yaml, capabilities.yaml,
-                                            # hooks.yaml
-# Edit the skill
-vim <slug>/SKILL.md
-# Push as a draft
-headways skills push <slug>
-# Publish via the web UI when ready
+headways skills new                          # creates ./<slug>/ with SKILL.md,
+                                             # headways.yaml, capabilities.yaml,
+                                             # hooks.yaml
+vim <slug>/SKILL.md                          # edit
+headways skills push <slug>                  # push as draft
+# Then publish via the web UI at app.headways.ai/skills/<slug>
 ```
 
-Installed skill bundles land in `~/.claude/skills/<slug>/`. Config is stored in `~/.headways/config.json`.
+Once published, the skill shows up in the desktop app's Library view with an **Install** button.
+
+## Where things live
+
+| Path | Purpose |
+|---|---|
+| `~/.headways/config.json` | API token, org, URLs |
+| `~/.headways/installed/<slug>.json` | Local install manifests (written by the desktop) |
+| `~/.headways/runs/<session_id>` | Active run id per Claude Code session (written by `skill-run start`) |
+| `~/.claude/skills/<slug>/` | Materialized skill bundles (written by the desktop) |
+| `~/.claude/settings.json` | Claude Code hook wiring (written by the desktop) |
 
 ## Local development
 

package/dist/{api-5EKGGFQ6.js → api-H34ZX4FL.js}

@@ -2,8 +2,8 @@
 import {
   apiRequest,
   rawRequest
-} from "./chunk-2INXZHRG.js";
-import "./chunk-UUFIIGTZ.js";
+} from "./chunk-GN2N6M4B.js";
+import "./chunk-COGZMSYS.js";
 export {
   apiRequest,
   rawRequest

package/dist/{chunk-UUFIIGTZ.js → chunk-COGZMSYS.js}

@@ -8,6 +8,7 @@ var HEADWAYS_DIR = join(homedir(), ".headways");
 var CONFIG_FILE = join(HEADWAYS_DIR, "config.json");
 var CATALOG_FILE = join(HEADWAYS_DIR, "catalog.json");
 var INSTALLED_DIR = join(HEADWAYS_DIR, "installed");
+var RUNS_DIR = join(HEADWAYS_DIR, "runs");
 var CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 function readConfig() {
   if (!existsSync(CONFIG_FILE)) return {};
@@ -43,6 +44,7 @@ export {
   CONFIG_FILE,
   CATALOG_FILE,
   INSTALLED_DIR,
+  RUNS_DIR,
   CLAUDE_SKILLS_DIR,
   readConfig,
   writeConfig,

package/dist/{chunk-2INXZHRG.js → chunk-GN2N6M4B.js}

@@ -2,7 +2,7 @@
 import {
   getApiUrl,
   requireAuth
-} from "./chunk-UUFIIGTZ.js";
+} from "./chunk-COGZMSYS.js";
 
 // src/lib/api.ts
 async function rawRequest(path, token, options = {}, apiUrl) {

package/dist/{config-XQHAXREA.js → config-APIR4RCR.js}

@@ -5,18 +5,20 @@ import {
   CONFIG_FILE,
   HEADWAYS_DIR,
   INSTALLED_DIR,
+  RUNS_DIR,
   getApiUrl,
   getAppUrl,
   readConfig,
   requireAuth,
   writeConfig
-} from "./chunk-UUFIIGTZ.js";
+} from "./chunk-COGZMSYS.js";
 export {
   CATALOG_FILE,
   CLAUDE_SKILLS_DIR,
   CONFIG_FILE,
   HEADWAYS_DIR,
   INSTALLED_DIR,
+  RUNS_DIR,
   getApiUrl,
   getAppUrl,
   readConfig,