@constraint/cli 0.3.1 → 0.3.3

package/README.md

@@ -70,6 +70,7 @@ constraint setup --agent codex --dry-run
 ```bash
 constraint skills list
 constraint skills list --search research
+constraint skills domains
 constraint skills inspect account-research
 constraint skills inspect account-research --files
 ```
@@ -129,9 +130,14 @@ constraint skills update --all --global
 Create or edit a standard Agent Skill folder locally, then upload it:
 
 ```bash
+constraint skills domains
 constraint skills upload ./account-research --domain sales_pipeline
 ```
 
+`constraint skills domains --json` returns the exact domain slugs where the
+authenticated user can upload skills. Agents should discover the destination
+first and pass one returned `slug` to `--domain`.
+
 The folder must contain a root `SKILL.md` with `name` and `description` YAML
 frontmatter. Pass the owning domain with `--domain`; if it is omitted in an
 interactive terminal, the CLI asks which permitted domain owns the skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constraint/cli",
-  "version": "0.3.1",
+  "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

@@ -23,13 +23,14 @@ import {
   configuredAgents,
   installSkill,
   installedSkills,
+  manageableDomainRecords,
   manageableDomains,
   readTranscript,
   updateAll,
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.1';
+const VERSION = '0.3.3';
 
 const HELP = `Constraint Skills CLI
 
@@ -39,6 +40,7 @@ Usage:
   constraint doctor [--agent codex|claude-code]...
   constraint skills list [--search <text>]
   constraint skills list --installed [--project|--global] [--agent <agent>]...
+  constraint skills domains
   constraint skills inspect <skill> [--version <version>] [--files]
   constraint skills install <skill> [--version <version>] [--agent <agent>]...
                             [--project|--global] [--copy] [--yes]
@@ -131,6 +133,39 @@ function printSkillList(items, options, out) {
   else out.line(`${presentation.title}\n${presentation.message}`);
 }
 
+export function domainListPresentation(domains) {
+  if (domains.length === 0) {
+    return {
+      title: 'No upload domains',
+      message: 'You do not have permission to upload skills to any domain.',
+    };
+  }
+  return {
+    title: `${domains.length} skill upload domain${domains.length === 1 ? '' : 's'}`,
+    message: domains.map((domain) => [
+      `${domain.name} (${domain.slug})`,
+      domain.description || 'No description.',
+    ].join('\n')).join('\n\n'),
+  };
+}
+
+async function listSkillDomains(args, config, out) {
+  rejectUnknown(args);
+  if (args.length) throw new Error('skills domains does not accept positional arguments');
+  const domains = (await manageableDomainRecords(config)).map(({ slug, name, description }) => ({
+    slug,
+    name,
+    description,
+  }));
+  if (out.json) {
+    out.data(domains);
+    return;
+  }
+  const presentation = domainListPresentation(domains);
+  if (interactive(out)) note(presentation.message, presentation.title);
+  else out.line(`${presentation.title}\n${presentation.message}`);
+}
+
 function takeScope(args) {
   const project = takeFlag(args, '--project');
   const global = takeFlag(args, '--global');
@@ -441,12 +476,13 @@ async function runCommand(args, config, out) {
 async function skillsCommand(args, config, out) {
   const command = args.shift();
   if (command === 'list') return listSkills(args, config, out);
+  if (command === 'domains') return listSkillDomains(args, config, out);
   if (command === 'inspect') return inspectSkill(args, config, out);
   if (command === 'install') return installCommand(args, config, out);
   if (command === 'update') return updateCommand(args, config, out);
   if (command === 'upload') return uploadCommand(args, config, out);
   if (command === 'run') return runCommand(args, config, out);
-  throw new Error('Expected skills list, inspect, install, update, upload, or run.');
+  throw new Error('Expected skills list, domains, inspect, install, update, upload, or run.');
 }
 
 export async function main(argv) {

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) {

package/src/skills.js

@@ -66,10 +66,12 @@ export async function uploadSkill(config, localPath, domain) {
 }
 
 export async function manageableDomains(config) {
+  return (await manageableDomainRecords(config)).map((domain) => domain.slug);
+}
+
+export async function manageableDomainRecords(config) {
   const domains = await apiRequest(config, '/domains');
-  return domains
-    .filter((domain) => domain.permissions.includes('domain:skill_manage'))
-    .map((domain) => domain.slug);
+  return domains.filter((domain) => domain.permissions.includes('domain:skill_manage'));
 }
 
 export async function configuredAgents() {