@purveyors/cli 0.35.1 → 0.36.0

package/README.md

@@ -11,7 +11,7 @@ Use `purvey --help` for quick command discovery, `purvey context` for the dense
 - Official binary: `purvey`
 - Package: `@purveyors/cli`
 - Runtime: Node.js 20+
-- No pre-existing credentials required: `auth`, `config`, `context`, `manifest`
+- No pre-existing credentials required: `auth`, `config`, `context`, `manifest`, `skill`
 - Viewer role required: `catalog` (excluding structured process filters on `catalog search`)
 - Member role required: `procurement`, `inventory`, `roast`, `sales`, `tasting`
 - Mixed public and entitled access: `market` and `price-index` public teaser slices are unauthenticated; filtered, non-public, and evidence slices require a credential and, where entitled, Parchment Intelligence access
@@ -19,6 +19,7 @@ Use `purvey --help` for quick command discovery, `purvey context` for the dense
 - Dense human-readable reference: `purvey context`
 - Compatibility JSON alias: `purvey context --json`
 - In-process machine contract: `@purveyors/cli/manifest`
+- Agent instructions generated from the manifest: `purvey skill print`, `purvey skill install`
 
 ## Installation
 
@@ -105,6 +106,7 @@ Use the right reference surface for the job:
 - `purvey context` is the dense human-readable operator reference for reviewers and interactive use.
 - `purvey context --json` and `purvey context --pretty` emit the same JSON payload as `purvey manifest`, but exist mainly for compatibility with tooling that already shells out to `context`.
 - `@purveyors/cli/manifest` exposes the same contract in-process for Node.js and agent runtimes.
+- `purvey skill print` renders an agent skill from the manifest: a compact SKILL.md plus workflows.md with the step-by-step workflows. `purvey skill install` puts it where Claude Code, Codex, or Cursor will load it, or adds a short block to a repository AGENTS.md.
 
 Manifest commands carry `sdkMethods`, the `@purveyors/sdk` operations whose canonical endpoints
 they consume, and, for writes, `confirmedActionEquivalents`, the Purveyors web assistant's
@@ -142,7 +144,7 @@ Export discipline:
 
 ## Authentication and access model
 
-No pre-existing credentials are required for `auth`, `config`, `context`, or `manifest`.
+No pre-existing credentials are required for `auth`, `config`, `context`, `manifest`, or `skill`.
 
 Remote data commands require a valid owner-bound API key with the required scope:
 
@@ -204,7 +206,7 @@ The `reference-profile` commands also require Studio access; the API enforces th
 
 Market Index teaser slices are public. Filtered `market signals`, origin/process/wholesale `market stats`, non-public `market metadata`, `market evidence`, `price-index comparisons`, `price-index comparison`, and `price-index history` windows over 90 days require Parchment Intelligence access; API-key denial is enforced by the canonical API. The stored login key carries `catalog:read`, which is also the canonical read scope for Market Index, Price Index, and procurement.
 
-`auth`, `config`, `context`, and `manifest` remain available without pre-existing credentials.
+`auth`, `config`, `context`, `manifest`, and `skill` remain available without pre-existing credentials.
 
 Commands that require a higher role exit with code `3` on auth failure. That includes missing, revoked, or invalid credentials and an insufficient role.
 
@@ -964,6 +966,39 @@ Notes:
 - Use `purvey manifest` for new automation and treat `purvey context --json` as a compatibility alias.
 - `--csv` is not supported.
 
+### skill
+
+- `purvey skill print [--file SKILL.md|workflows.md|all]`
+- `purvey skill print --agents-md`
+- `purvey skill install --target <claude|agents|agents-md> [--scope user|project] [--force] [--dry-run] [--link-claude-md]`
+
+The skill is a folder in the open [Agent Skills](https://agentskills.io/specification) format, rendered from `purvey manifest` so it changes only when the CLI contract changes:
+
+- `SKILL.md` loads whenever the skill triggers. It covers when to use `purvey`, headless sign-in, output and exit codes, the ID map, an index of workflows, and working rules, and points to `purvey manifest` for everything else.
+- `workflows.md` holds the step-by-step command sequence for each manifest workflow. `SKILL.md` links to it and tells the agent to read it before a multi-step task, so it is loaded only when needed ([Claude Code](https://code.claude.com/docs/en/skills#add-supporting-files), [Agent Skills](https://agentskills.io/specification#progressive-disclosure)).
+
+`skill print` writes `SKILL.md` to stdout; `--file workflows.md` prints the other file. `--json` or `--pretty` wraps one file as `{ name, file, cliVersion, bytes, content }`, and `--file all --json` prints both as `{ name, cliVersion, files: [{ file, bytes, content }] }`. `--agents-md` prints a shorter block for a repository's AGENTS.md instead.
+
+`skill install` writes the same content to a location an agent loads:
+
+| Target      | User scope (default)                                           | Project scope (`--scope project`)                 | Loaded by                                                       |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------- |
+| `claude`    | `SKILL.md` and `workflows.md` in `~/.claude/skills/purveyors/` | the same files in `.claude/skills/purveyors/`     | Claude Code                                                     |
+| `agents`    | `SKILL.md` and `workflows.md` in `~/.agents/skills/purveyors/` | the same files in `.agents/skills/purveyors/`     | Codex, Cursor, and other Agent Skills clients (not Claude Code) |
+| `agents-md` | n/a                                                            | one block in `AGENTS.md` in the current directory | Codex and Cursor; Claude Code only as described below           |
+
+Notes:
+
+- No credentials or network access are needed.
+- Prints `{ target, scope, path, action, written, dryRun, cliVersion, bytes }` as JSON; `action` is `create`, `update`, `unchanged`, `append`, or `overwrite`.
+- `claude` and `agents` also print `files: [{ file, path, action, written, bytes }]`, one entry per file. The top-level `path` is `SKILL.md`, `action` is the most significant file action (`overwrite`, then `update`, `create`, `unchanged`), `written` is true when any file changed, and `bytes` is the total.
+- Re-running is safe. Identical files are left alone, an unedited file from an earlier CLI version is updated in place, and a missing `workflows.md` is created, so a `SKILL.md`-only install from an earlier version upgrades cleanly. Rerun after upgrading the CLI.
+- Each file is checked on its own. A file with local edits, or one `purvey` did not write, is refused with exit code `6` unless you pass `--force`; the refusal names every such file and writes nothing. `--dry-run` reports the paths and actions without writing.
+- `agents-md` adds one marked block to `AGENTS.md` (creating the file if needed) and leaves the rest of the file untouched.
+- Claude Code loads skills only from `.claude/skills`, so use `--target claude` for it. It does not read `.agents/`.
+- Claude Code reads `AGENTS.md` only as a fallback: when a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the current directory or any directory above it, it reads those instead, unless one imports `@AGENTS.md` ([Claude Code docs](https://code.claude.com/docs/en/memory#agents-md)). `agents-md` reports this as `claudeCode: { visible, via, reason, claudeMdFiles }` in its JSON output and prints a warning on stderr when Claude Code will not see the block. It does not change your `CLAUDE.md` unless you ask.
+- `--link-claude-md` (with `agents-md`) adds that import: one `@AGENTS.md` line appended to `./CLAUDE.md` (or `@../AGENTS.md` to `./.claude/CLAUDE.md`), creating `./CLAUDE.md` if neither exists. It is a no-op when Claude Code already sees the block, honors `--dry-run`, and never edits `CLAUDE.local.md` or a parent directory's `CLAUDE.md`. `claudeCode.link` reports `{ path, action, written }`, where `action` is `create`, `append`, `unchanged`, or `not-needed`.
+
 ### In-process manifest export
 
 - `@purveyors/cli/manifest`
@@ -1055,11 +1090,13 @@ Use the right ID for the right command.
 Recommended bootstrap order:
 
 ```bash
-purvey manifest
-purvey context
+purvey skill install --target claude   # Claude Code; Codex and Cursor: --target agents
 purvey auth login --headless
+purvey manifest
 ```
 
+The installed skill gives a coding agent the sign-in flow, output contract, and ID map up front, the step-by-step workflows in `workflows.md` when a task needs them, and `purvey manifest` for the full contract.
+
 Use `purvey manifest` as the authoritative machine-readable entry point. Keep `purvey context` for dense operator context, or use `purvey context --json` only when you need compatibility with an existing wrapper.
 
 Why this CLI works well for agents:
@@ -1105,7 +1142,7 @@ Use the [ID reference](#id-reference) section above. `catalog_id` and inventory
 
 **Pagination only shows the first page**
 
-All list commands default to 20 results. Use `--limit` and `--offset`.
+Only `catalog search` (default 10 results), `inventory list`, `roast list`, and `sales list` (default 20) page with `--limit` and `--offset`.
 
 ```bash
 purvey inventory list --limit 20 --offset 0

package/dist/commands/skill.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function buildSkillCommand(version: string): Command;
+//# sourceMappingURL=skill.d.ts.map

package/dist/commands/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/commands/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2DpC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsK1D"}

package/dist/commands/skill.js

@@ -0,0 +1,145 @@
+import { Command } from 'commander';
+import { AGENT_SKILL_FILE, AGENT_SKILL_FILES, AGENT_SKILL_NAME, installAgentSkill, renderAgentSkillFile, renderAgentsMdBlock, } from '../lib/agent-skill.js';
+import { PrvrsError, withErrorHandling } from '../lib/errors.js';
+import { info, outputData, shouldUseInteractiveOutput, success, warn } from '../lib/output.js';
+const ACTION_LABELS = {
+    create: 'Created',
+    update: 'Updated',
+    unchanged: 'Already current:',
+    append: 'Appended the purvey block to',
+    overwrite: 'Replaced',
+};
+function sized(content) {
+    return { bytes: Buffer.byteLength(content, 'utf8'), content };
+}
+function parsePrintFile(value, fileGiven, agentsMd, structured) {
+    if (agentsMd) {
+        if (fileGiven) {
+            throw new PrvrsError('INVALID_ARGUMENT', '--agents-md prints the AGENTS.md block and cannot be combined with --file.');
+        }
+        return 'agents-md';
+    }
+    if (value === 'all') {
+        if (!structured) {
+            throw new PrvrsError('INVALID_ARGUMENT', '--file all prints several files, so it needs --json or --pretty. Use --file SKILL.md or --file workflows.md for Markdown.');
+        }
+        return [...AGENT_SKILL_FILES];
+    }
+    if (!AGENT_SKILL_FILES.includes(value)) {
+        throw new PrvrsError('INVALID_ARGUMENT', `Unknown --file "${value}". Use one of: ${AGENT_SKILL_FILES.join(', ')}, all.`);
+    }
+    return [value];
+}
+export function buildSkillCommand(version) {
+    const skill = new Command('skill').description('Print or install agent instructions generated from the CLI manifest');
+    skill
+        .command('print')
+        .description('Write the generated SKILL.md, workflows.md, or the AGENTS.md block to stdout')
+        .option('--file <file>', `Skill file to print: ${AGENT_SKILL_FILES.join(', ')}, or all (needs --json or --pretty)`, AGENT_SKILL_FILE)
+        .option('--agents-md', 'Print the compact AGENTS.md block instead of the skill')
+        .addHelpText('after', `
+The skill is a folder: SKILL.md, which agents load first, and workflows.md, which it points to for
+step-by-step workflows. Prints SKILL.md as Markdown by default. --json or --pretty wraps one file as
+{ name, file, cliVersion, bytes, content }, or every file with --file all as
+{ name, cliVersion, files: [{ file, bytes, content }] }.
+The output is rendered from \`purvey manifest\`; no credentials are needed.
+
+Examples:
+  purvey skill print
+  purvey skill print --file workflows.md
+  purvey skill print --file all --json
+  purvey skill print --agents-md
+  purvey skill print > SKILL.md
+`)
+        .action(withErrorHandling(async (opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        if (globalOpts.csv) {
+            throw new PrvrsError('INVALID_ARGUMENT', 'The skill print command does not support --csv. Use Markdown (default), --json, or --pretty.');
+        }
+        const structured = Boolean(globalOpts.json || globalOpts.pretty);
+        const files = parsePrintFile(opts.file, cmd.getOptionValueSource('file') !== 'default', Boolean(opts.agentsMd), structured);
+        if (files === 'agents-md') {
+            const content = renderAgentsMdBlock(version);
+            if (structured) {
+                outputData({ name: AGENT_SKILL_NAME, file: 'AGENTS.md', cliVersion: version, ...sized(content) }, { pretty: globalOpts.pretty });
+            }
+            else {
+                process.stdout.write(content);
+            }
+            return;
+        }
+        const rendered = files.map((file) => ({
+            file,
+            ...sized(renderAgentSkillFile(file, version)),
+        }));
+        if (!structured) {
+            process.stdout.write(rendered[0].content);
+        }
+        else if (opts.file === 'all') {
+            outputData({ name: AGENT_SKILL_NAME, cliVersion: version, files: rendered }, { pretty: globalOpts.pretty });
+        }
+        else {
+            const [{ file, ...rest }] = rendered;
+            outputData({ name: AGENT_SKILL_NAME, file, cliVersion: version, ...rest }, { pretty: globalOpts.pretty });
+        }
+    }));
+    skill
+        .command('install')
+        .description('Install the generated instructions for Claude Code, Agent Skills clients such as Codex and Cursor, or a repository AGENTS.md')
+        .option('--target <target>', 'claude, agents, or agents-md (required)')
+        .option('--scope <scope>', 'user (home directory) or project (current directory); defaults to user, or project for agents-md')
+        .option('--force', 'Replace skill files or an AGENTS.md block that have local edits')
+        .option('--dry-run', 'Report the path and action without writing')
+        .option('--link-claude-md', 'agents-md only: add an @AGENTS.md import to ./CLAUDE.md so Claude Code loads the block')
+        .addHelpText('after', `
+Targets:
+  claude      ~/.claude/skills/purveyors/{SKILL.md,workflows.md}   (Claude Code)
+  agents      ~/.agents/skills/purveyors/{SKILL.md,workflows.md}   (Codex, Cursor, other Agent Skills clients)
+  agents-md   ./AGENTS.md, as one marked block                      (repository-level instructions)
+
+claude and agents write a skill folder: SKILL.md, which agents load first, and workflows.md, the
+step-by-step workflows it points to. Each file is checked and reported on its own under "files".
+Claude Code loads skills only from .claude/skills, so use --target claude there; it does not read .agents/.
+--scope project writes .claude/skills/... or .agents/skills/... under the current directory instead.
+
+Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the
+current directory or above it. agents-md reports this as "claudeCode" in its JSON output. --link-claude-md
+adds an @AGENTS.md import to ./CLAUDE.md (or ./.claude/CLAUDE.md), creating ./CLAUDE.md if needed, and never
+edits CLAUDE.local.md or a parent directory's CLAUDE.md. See https://code.claude.com/docs/en/memory#agents-md
+Re-running is safe: identical files are left alone, unedited earlier output is updated, and a missing
+workflows.md is created. If any file has local edits, nothing is written and the command exits 6 unless
+--force is passed. No credentials are needed.
+
+Examples:
+  purvey skill install --target claude
+  purvey skill install --target agents --dry-run
+  purvey skill install --target claude --scope project
+  purvey skill install --target agents-md
+  purvey skill install --target agents-md --link-claude-md
+`)
+        .action(withErrorHandling(async (opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        const result = await installAgentSkill({ ...opts, version });
+        if (shouldUseInteractiveOutput(globalOpts)) {
+            for (const { action, path } of result.files ?? [result]) {
+                if (result.dryRun) {
+                    info(`Dry run, nothing written. Would ${action}: ${path}`);
+                }
+                else {
+                    success(`${ACTION_LABELS[action]} ${path}`);
+                }
+            }
+            if (result.claudeCode?.visible) {
+                info(result.claudeCode.reason);
+            }
+        }
+        const { claudeCode } = result;
+        if (claudeCode && !claudeCode.visible) {
+            // Always on stderr, so agents running non-interactively see it too.
+            warn(`Claude Code will not load this block. ${claudeCode.reason}`);
+        }
+        outputData(result, globalOpts);
+    }));
+    return skill;
+}
+//# sourceMappingURL=skill.js.map

package/dist/commands/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/commands/skill.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent-skill.d.ts

@@ -0,0 +1,110 @@
+import { type CliManifest } from './manifest.js';
+/**
+ * Agent instructions rendered from the CLI manifest. The manifest stays the
+ * single source of truth: commands, flags, auth, output, exit codes, ID types,
+ * and workflows all come from `getCliManifest()`, so the skill cannot drift
+ * from the contract it describes.
+ */
+export declare const AGENT_SKILL_NAME = "purveyors";
+export declare const AGENT_SKILL_FILE = "SKILL.md";
+/**
+ * Supporting file in the same skill folder. Agent Skills clients load SKILL.md
+ * when the skill triggers and read other files only when SKILL.md points to
+ * them, so the step-by-step workflows, which grow with the manifest, live here.
+ * See https://code.claude.com/docs/en/skills#add-supporting-files and
+ * https://agentskills.io/specification#progressive-disclosure
+ */
+export declare const AGENT_WORKFLOWS_FILE = "workflows.md";
+/** Every file in the skill folder, SKILL.md first. */
+export declare const AGENT_SKILL_FILES: readonly ["SKILL.md", "workflows.md"];
+export type AgentSkillFile = (typeof AGENT_SKILL_FILES)[number];
+/** Upper bound for the rendered SKILL.md, enforced by tests. */
+export declare const AGENT_SKILL_MAX_BYTES: number;
+/** Upper bound for the rendered workflows.md, enforced by tests. */
+export declare const AGENT_WORKFLOWS_MAX_BYTES: number;
+export declare const AGENT_SKILL_DESCRIPTION: string;
+export declare const SKILL_TARGETS: readonly ["claude", "agents", "agents-md"];
+export declare const SKILL_SCOPES: readonly ["user", "project"];
+export type SkillTarget = (typeof SKILL_TARGETS)[number];
+export type SkillScope = (typeof SKILL_SCOPES)[number];
+export type SkillInstallAction = 'create' | 'update' | 'unchanged' | 'append' | 'overwrite';
+export interface SkillInstallFileResult {
+    file: AgentSkillFile;
+    path: string;
+    action: SkillInstallAction;
+    written: boolean;
+    bytes: number;
+}
+export interface SkillInstallResult {
+    target: SkillTarget;
+    scope: SkillScope;
+    /** SKILL.md for claude and agents, AGENTS.md for agents-md. */
+    path: string;
+    /** For claude and agents, summarizes `files`: overwrite, then update, then create, then unchanged. */
+    action: SkillInstallAction;
+    /** True when any file was written. */
+    written: boolean;
+    dryRun: boolean;
+    cliVersion: string;
+    /** Total bytes across the installed content. */
+    bytes: number;
+    /** claude and agents only: each file in the skill folder, SKILL.md first. */
+    files?: SkillInstallFileResult[];
+    /** agents-md only: whether Claude Code will load the AGENTS.md block. */
+    claudeCode?: ClaudeCodeVisibility;
+}
+export type ClaudeMdLinkAction = 'create' | 'append' | 'unchanged' | 'not-needed';
+/**
+ * Claude Code reads AGENTS.md only as a fallback: when a CLAUDE.md,
+ * .claude/CLAUDE.md, or CLAUDE.local.md sits in the project directory or any
+ * directory above it, it reads those instead, unless one imports AGENTS.md.
+ * See https://code.claude.com/docs/en/memory#agents-md
+ */
+export interface ClaudeCodeVisibility {
+    visible: boolean;
+    /** How Claude Code loads the block: AGENTS.md directly, a CLAUDE.md import, or not at all. */
+    via: 'agents-md' | 'claude-md-import' | null;
+    reason: string;
+    /** CLAUDE.md files on the path that take precedence over AGENTS.md. */
+    claudeMdFiles: string[];
+    /** Present with --link-claude-md. */
+    link?: {
+        path: string | null;
+        action: ClaudeMdLinkAction;
+        written: boolean;
+    };
+}
+/** Render SKILL.md in the open Agent Skills format. */
+export declare function renderAgentSkill(version: string, manifest?: CliManifest): string;
+/** Render workflows.md, the supporting file SKILL.md points to for step-by-step workflows. */
+export declare function renderAgentWorkflows(version: string, manifest?: CliManifest): string;
+/** Render one file of the skill folder. */
+export declare function renderAgentSkillFile(file: AgentSkillFile, version: string, manifest?: CliManifest): string;
+/** Render the marked AGENTS.md block; markers let `install` refresh it in place. */
+export declare function renderAgentsMdBlock(version: string, manifest?: CliManifest): string;
+export declare function resolveSkillInstallPath(target: SkillTarget, scope: SkillScope, roots?: {
+    home?: string;
+    cwd?: string;
+}): string;
+export declare const CLAUDE_CODE_AGENTS_MD_DOCS = "https://code.claude.com/docs/en/memory#agents-md";
+export interface SkillInstallOptions {
+    target?: string;
+    scope?: string;
+    force?: boolean;
+    dryRun?: boolean;
+    /** agents-md only: add an `@AGENTS.md` import so Claude Code loads the block past a CLAUDE.md. */
+    linkClaudeMd?: boolean;
+    version: string;
+    manifest?: CliManifest;
+    home?: string;
+    cwd?: string;
+}
+/**
+ * Install the generated instructions. Never touches credentials or the network.
+ * claude and agents write both files of the skill folder; agents-md writes one
+ * block. Identical content is left alone, unedited earlier output is updated,
+ * and anything else needs `force`. For agents-md, also reports whether Claude Code
+ * will load the block, and with `linkClaudeMd` makes sure it does.
+ */
+export declare function installAgentSkill(options: SkillInstallOptions): Promise<SkillInstallResult>;
+//# sourceMappingURL=agent-skill.d.ts.map

package/dist/lib/agent-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skill.d.ts","sourceRoot":"","sources":["../../src/lib/agent-skill.ts"],"names":[],"mappings":"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"}