@constraint/cli 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constraint/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Install, publish, and report Agent Skills with Constraint",
   "type": "module",
   "bin": {

package/skills/constraint-skills/SKILL.md

@@ -1,44 +1,71 @@
 ---
 name: constraint-skills
-description: Report Agent Skill invocations to Constraint. Use whenever an agent invokes a skill installed from or governed by Constraint, including nested or multiple skill invocations in one client session.
+description: Operate governed Agent Skills with the Constraint terminal CLI and report their invocations. Use when an agent needs to authenticate or diagnose Constraint access; configure agents; discover upload domains; inspect, install, update, or upload skills; query run history; or invoke any skill installed from or governed by Constraint.
 ---
 
 # Constraint Skills
 
-Record each invocation without editing the invoked skill or changing its work.
+Use the `constraint` command for organization-authorized skills. Do not edit its config, lockfiles, instruction blocks, installation receipts, or authorization tokens directly.
+
+## Choose the operation
+
+- Authenticate or diagnose: `constraint login`, `constraint whoami`, `constraint doctor`.
+- Configure agents: `constraint setup`.
+- Discover or inspect skills: `constraint skills list`, `constraint skills inspect`.
+- Install or update: `constraint skills install`, `constraint skills update`.
+- Discover upload destinations: `constraint skills domains --json`.
+- Upload a local skill folder: `constraint skills upload`.
+- Review runs: `constraint skills run list`, `constraint skills run get`.
+
+Read [references/commands.md](references/commands.md) before constructing flags or handling a less common operation.
+
+## Upload skills
+
+Upload the skill directory, not an individual `SKILL.md`. Before every upload, run:
+
+```bash
+constraint skills domains --json
+```
+
+Use one returned `slug` exactly as `--domain`. Never guess a slug from a display name or reuse a domain from another organization. If multiple destinations are valid and ownership is unclear, ask the user.
+
+```bash
+constraint skills upload <skill-directory> --domain <returned-slug>
+```
+
+## Install skills
+
+Choose the target agent and scope explicitly. Prefer `--project`; use `--global` only when the user wants the skill across projects. Prefer managed links and use `--copy` only when independent files are required. Never overwrite locally edited installed skills.
 
 ## Start a run
 
-Immediately after selecting and loading a skill, run:
+Immediately after selecting and loading a governed skill, run:
 
 ```bash
 constraint skills run start <skill-name> --client <client> --session <session-id>
 ```
 
-Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or
-`claude-code`. Use the current client session identifier. Retain the exact run ID
-printed by the command. If one session invokes multiple skills, start and retain
-a distinct run ID for each invocation.
+Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or `claude-code`. Use the current client session identifier. Retain the exact run ID printed by the command. If one session invokes multiple skills, start and retain a distinct run ID for each invocation.
 
-If the command fails, report the failure briefly and continue the user's work.
-Do not fabricate a run ID.
+If the command fails, report the failure briefly and continue the user's work. Do not fabricate a run ID.
 
 ## Complete a run
 
-After finishing the invoked skill's work and before ending the response, locate
-the current session's real JSON or JSONL transcript file and run:
+After finishing the governed skill's work and before ending the response, locate the current session's real JSON or JSONL transcript file and run:
 
 ```bash
 constraint skills run complete <run-id> <transcript-path>
 ```
 
-Pass the explicit local path. The CLI uploads the whole transcript file as it
-exists at that moment and completes only that run. Never create a replacement
-transcript, summarize it, pass a temporary file, or guess a path.
+Pass the explicit local path. The CLI uploads the whole transcript file as it exists at that moment and completes only that run. Never create a replacement transcript, summarize it, pass a temporary file, or guess a path.
 
-For multiple invocations, complete each retained run separately. Overlapping
-full-session transcript prefixes are expected. If the transcript path cannot be
-determined, leave the run started and tell the user that reporting could not be
-completed.
+For multiple invocations, complete each retained run separately. Overlapping full-session transcript prefixes are expected. If the transcript path cannot be determined, leave the run started and tell the user that reporting could not be completed.
 
 Do not run completion hooks, background flushes, or pending-run scans.
+
+## Work safely
+
+- Use `--json` when parsing output.
+- Respect WorkOS authorization failures; never bypass domain permissions.
+- Do not invent an uninstall workflow.
+- After mutations, report the affected skill, version, agent, scope, domain, or run ID as applicable.

package/skills/constraint-skills/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Constraint Skills"
-  short_description: "Report skill runs to Constraint"
-  default_prompt: "Use $constraint-skills to report this skill run to Constraint."
+  short_description: "Operate and report governed agent skills"
+  default_prompt: "Use $constraint-skills to manage a governed skill and report its run."

package/skills/constraint-skills/references/commands.md

@@ -0,0 +1,65 @@
+# Constraint CLI command reference
+
+## Install, authenticate, and configure
+
+```bash
+npm install --global @constraint/cli
+constraint --version
+constraint login
+constraint whoami
+constraint logout
+constraint setup
+constraint doctor
+```
+
+`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, installs this skill, and deterministically merges a marked global instruction block without replacing unrelated instructions.
+
+## Discover, inspect, install, and update
+
+```bash
+constraint skills list
+constraint skills list --search <text>
+constraint skills inspect <skill> [--version <number>] [--files]
+
+constraint skills install <skill> --agent codex --project
+constraint skills install <skill> --agent claude-code --global
+constraint skills list --installed --project
+constraint skills update <skill> --project
+constraint skills update --all --global
+```
+
+The catalog is already authorization-filtered. Project installs create `skills-lock.json`. Global receipts live in Constraint's per-user configuration directory.
+
+## Discover upload domains and upload
+
+```bash
+constraint skills domains
+constraint skills domains --json
+constraint skills upload <skill-directory> --domain <returned-slug>
+```
+
+`skills domains` returns only domains where the authenticated user can manage skills. JSON objects contain the exact `slug`, display `name`, and `description`. Discover first and pass one returned slug. Ask the user when multiple domains fit and ownership is unclear.
+
+## Start, complete, and review runs
+
+```bash
+constraint skills run start <skill> --client codex --session <stable-session-id>
+constraint skills run complete <run-id> <actual-transcript-path>
+
+constraint skills run list
+constraint skills run list --team <domain> --user <workos-user-id> --skill <skill>
+constraint skills run get <run-id>
+constraint skills run get <run-id> --raw --output transcript.jsonl
+```
+
+Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.
+
+## Automation and recovery
+
+Global flags: `--json`, `--quiet`, `--no-color`, `--help`, and `--version`. Installer workflows also accept `--yes`.
+
+- Authentication failure: run `constraint login`, then `constraint whoami`.
+- Setup uncertainty: run `constraint doctor`.
+- Upload denied: rerun `constraint skills domains --json` and respect the returned scope.
+- Install conflict: preserve local edits.
+- Missing transcript: locate the real client JSON or JSONL file before completion.

package/src/cli.js

@@ -30,7 +30,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.2';
+const VERSION = '0.3.3';
 
 const HELP = `Constraint Skills CLI
 

package/src/setup.js

@@ -12,9 +12,9 @@ export const BLOCK_END = '<!-- constraint-skills:end -->';
 const BLOCK = `${BLOCK_START}
 ## Constraint Skills
 
-When invoking any installed Agent Skill, load and follow the global
-\`constraint-skills\` companion skill. It records the run with the Constraint
-CLI without modifying the invoked skill.
+When using the Constraint CLI or invoking any installed Agent Skill, load and
+follow the global \`constraint-skills\` companion skill. It contains the CLI
+workflow and records governed runs without modifying the invoked skill.
 ${BLOCK_END}`;
 
 export function mergeInstructionBlock(existing) {