@holdyourvoice/hyv 3.3.5 → 3.4.1

package/Readme.md

@@ -2,168 +2,118 @@
 
 [![npm downloads](https://img.shields.io/npm/dt/%40holdyourvoice%2Fhyv?label=npm%20downloads&color=2f81f7)](https://www.npmjs.com/package/@holdyourvoice/hyv)
 
-Hold Your Voice is a local-first writing gate. It helps you use AI without losing the parts of your writing that make it yours.
+Hold Your Voice (`hyv`) is a local writing checker. It helps you edit AI-assisted writing without losing your own writing patterns.
 
-It runs two checks on a draft, with separate scores and pass states. A strong result in one engine leaves the other engine's finding unchanged.
+It runs two independent checks:
 
-- **VoiceDNA** compares your draft with observable elements from your own writing samples.
-- **AI Editor** flags a versioned set of editorial patterns that make writing sound generic or formulaic.
+- VoiceDNA compares a draft with a profile built from your writing samples.
+- AI Editor finds deterministic patterns that often make writing generic or formulaic.
 
-Everything runs from local files. There are no accounts, no telemetry, and no runtime network requests. The optional Claude extension is a local adapter around the same engine.
+The package also checks hidden Unicode, source-backed facts, document logic, and protected claims. All checks run locally, without model calls, automatic draft changes, or runtime network requests.
 
-> **Status:** [`@holdyourvoice/hyv`](https://www.npmjs.com/package/@holdyourvoice/hyv) runs locally and makes no runtime network requests.
+## install
 
-## Start here
-
-**Requirements:** Node.js 20+, npm, and at least two writing samples you have the right to use.
-
-### Install
+You need Node.js 20 or newer and at least two writing samples you have the right to use.
 
 ```bash
 npm install --global @holdyourvoice/hyv
-hyv patterns
 ```
 
-No global install? Run any command with `npx @holdyourvoice/hyv`.
+For a one-off command, replace `hyv` with `npx @holdyourvoice/hyv`.
+
+## basic workflow
 
-### Build a profile
+1. Build a local profile from your samples.
 
 ```bash
-hyv profile profile.json samples/one.md samples/two.md --avoid=overused-phrase
+hyv profile profile.json samples/one.md samples/two.md
 ```
 
-Use writing by one person, with a similar audience and format. The command needs at least two samples. It writes a portable JSON profile and keeps your samples on your machine. Repeat `--avoid=phrase` for each phrase that must block a candidate.
+Add `--avoid=phrase` for wording that must block a draft. Repeat the option for more phrases.
 
-### Analyze a draft
+2. Check a draft against that profile.
 
 ```bash
 hyv analyze draft.md profile.json
 ```
 
-The result is JSON with independent reports. The outer `passed` field is true only when each engine passes.
-
-```json
-{
-  "voiceDna": { "score": 93, "passed": true, "findings": [] },
-  "aiEditor": { "score": 88, "passed": true, "findings": [] },
-  "hygiene": { "suspiciousCount": 0, "fixableCount": 0, "hits": [] },
-  "passed": true
-}
-```
+The result contains separate VoiceDNA and AI Editor reports. The top-level `passed` value is true only when every required check passes.
 
-### Edit and verify
+3. Create an editing brief, edit the draft, and verify the candidate.
 
 ```bash
 hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
 hyv verify draft.md candidate.md profile.json
 ```
 
-Give the brief and draft to a human editor or any model you trust. Ask for replacement sentences keyed by sentence number, then save them as a separate candidate file. `verify` compares the original and candidate, reports new findings, and exits `2` when the candidate fails the gate.
+Send the brief to a human editor or a model you choose. Delivery stays under your control.
 
-### Gate final output
+4. Check the exact text before delivery.
 
 ```bash
+hyv final-check candidate.md
 producer | hyv final-check -
-hyv final-check final-response.md
 ```
 
-`final-check` is the last step before text reaches a user. It needs no profile. Clean text goes to stdout byte-for-byte. If hidden Unicode remains, stdout stays empty and the command exits `2`. Run it after the last edit, formatter, or template expansion.
+`final-check` writes accepted text to stdout. It withholds output and exits with code `2` when unresolved hidden Unicode remains.
 
-### Clean hidden Unicode
+## commands
 
-```bash
-hyv hygiene draft.md
-hyv hygiene draft.md --fix
-```
+| Command | Purpose |
+| --- | --- |
+| `hyv profile <profile.json> <sample...>` | Build a local profile from two or more samples. |
+| `hyv analyze <draft> <profile.json>` | Run VoiceDNA, AI Editor, and hygiene checks. |
+| `hyv hygiene <draft> [--fix]` | Inspect hidden Unicode or write a conservative cleaned copy. |
+| `hyv inspect-hidden-text <draft> [policy.json]` | Inspect hidden text with an optional policy. |
+| `hyv apply-hidden-text-policy <draft> <policy.json> <output>` | Apply approved hidden-text removals. |
+| `hyv final-check <path\|->` | Gate the exact text before delivery. |
+| `hyv fact-lint <draft\|-> --source=id:path` | Check claims against local source files. |
+| `hyv logic-lint <draft\|-> [brief.json]` | Check deterministic document logic. |
+| `hyv batch-analyze <draft...>` | Find repeated openings and endings across drafts. |
+| `hyv rewrite-prompt <draft> <profile.json>` | Create a constrained editing brief. |
+| `hyv prepare-rewrite ...` | Create a fingerprint-bound edit task. |
+| `hyv apply-rewrite ...` | Apply and verify a response to an edit task. |
+| `hyv prepare-judgment ...` | Create a pre-edit or post-candidate judgment task. |
+| `hyv reduce-judgment <envelope...>` | Reduce judgments to SHIP, EDIT, REBUILD, CLEAR, or ESCALATE. |
+| `hyv prepare-rebuild ...` | Create an authorized whole-document rebuild task. |
+| `hyv rebuild-writer-request ...` | Create the writer-only part of a rebuild task. |
+| `hyv apply-rebuild ...` | Apply and verify an authorized rebuild response. |
+| `hyv verify <original> <candidate> <profile.json>` | Verify a candidate without changing learning state. |
+| `hyv verify-spec ...` | Verify a candidate and a CopySpec. |
+| `hyv lifecycle ...` | Run semantic review and final approval steps. |
+| `hyv learning ...` | Inspect or change local profile learning. |
+| `hyv patterns` | Print the active AI Editor rule catalog. |
+| `hyv agent list\|validate\|describe\|emit` | Inspect or emit portable agent contracts. |
+| `hyv mcp` | Start the local MCP server on standard input/output. |
 
-Inspect zero-width characters, bidirectional controls, tag characters, and unusual spaces. Add `--fix` to write a cleaned copy while leaving the original untouched. The cleaner only removes non-semantic ASCII controls and byte-order marks; everything else is reported for review because it can carry real meaning.
-
-## The editing loop
-
-```mermaid
-flowchart LR
-  S[Your samples] --> P[Build profile]
-  P --> D[VoiceDNA profile]
-  T[Draft] --> A[Analyze]
-  D --> A
-  A --> V[VoiceDNA report]
-  A --> E[AI Editor report]
-  V --> B[Tiered brief]
-  E --> B
-  B --> C[Human or chosen model]
-  T --> G[Verify candidate]
-  C --> G
-  D --> G
-  G --> R[Errors block; findings stay visible]
-  R --> H[final-check before output]
-```
+Most commands return JSON. Exit code `0` means the command completed, `2` means a content or policy gate failed, and `1` means the command or input was invalid.
 
-The tool never edits your draft. You decide which findings are valid, apply the changes yourself, and run the final check.
+Run `hyv <command>` without enough arguments to see its exact usage. Read the [CLI reference](docs/wiki/CLI-Reference.md) for every option.
 
-## A few more commands
+## portable agents and MCP
 
-| Command | Use it when |
-| --- | --- |
-| `hyv verify-spec` | A draft has facts that must stay verbatim (CopySpec). |
-| `hyv fact-lint` | Check a draft against local evidence sources. |
-| `hyv batch-analyze` | Catch exact repeated sentences across drafts. |
-| `hyv prepare-rewrite` / `apply-rewrite` | Fingerprint-bound sentence or range edits. |
-| `hyv prepare-rebuild` / `apply-rebuild` | Whole-document rebuild after an authorized recommendation. |
-| `hyv prepare-judgment` / `reduce-judgment` | Reduce findings to SHIP, EDIT, or REBUILD. |
-| `hyv lifecycle` | Semantic and human-review lifecycle steps. |
-| `hyv learning show` | Inspect local voice-memory preferences. |
-
-## Commands
-
-| Command | Input | Output |
-| --- | --- | --- |
-| `hyv profile <profile.json> <sample...>` | Two or more text files | Profile JSON |
-| `hyv analyze <draft> <profile.json>` | Draft and profile | Analysis JSON |
-| `hyv hygiene <draft> [--fix] [--output=path]` | Draft | Hygiene report or cleaned copy plus receipt |
-| `hyv final-check <path\|->` | Any final text | Accepted text on stdout or a withheld-output report |
-| `hyv rewrite-prompt <draft> <profile.json>` | Draft and profile | Markdown editing brief |
-| `hyv prepare-rewrite <draft> <profile.json> <task.json>` | Draft and profile | Versioned task file |
-| `hyv apply-rewrite <task.json> <response.json> <profile.json>` | Task, response, profile | Candidate evaluation JSON |
-| `hyv prepare-judgment <pre-edit\|post-candidate> <kind> <draft> <profile.json> <task.json> [candidate.md]` | Draft, profile, optional candidate | Versioned judgment task |
-| `hyv reduce-judgment <envelope.json> ...` | Signed judgment envelopes | Recommendation JSON |
-| `hyv prepare-rebuild <draft> <profile.json> <reduction.json> <copy-spec.json> <task.json> [--recomposition-policy policy.json]` | Draft, recommendation, CopySpec, capability, optional policy | Versioned rebuild task |
-| `hyv apply-rebuild <task.json> <response.json> <profile.json>` | Task, response, profile, capability | Candidate evaluation JSON |
-| `hyv verify <original> <candidate> <profile.json>` | Original, candidate, profile | Verification JSON and exit code |
-| `hyv verify-spec <original> <candidate> <profile.json> <copy-spec.json>` | Original, candidate, profile, CopySpec | Verification JSON with hard claim gate |
-| `hyv learning <show\|inspect\|add\|record\|ratify\|supersede\|migrate\|clear> ...` | Profile, operation, bounded metadata | Preferences or a text-free receipt |
-| `hyv lifecycle <prepare-semantic\|submit-verdict\|inspect\|validate-final-approval\|finalize> ...` | Versioned lifecycle artifacts | Lifecycle artifact or metadata |
-| `hyv patterns` | None | Ruleset JSON |
-
-Every file argument can be `-` when the command accepts input on standard input. Use `npx @holdyourvoice/hyv <command>` if you have not installed the CLI globally.
-
-## Privacy
-
-Your samples, drafts, profiles, and candidates stay on your machine. Verification is read-only. Learning commands can write text-free local events under `~/.hyv/learning/` — profile fingerprint, finding IDs, counts, and an opaque digest. No writing text is uploaded, and the package makes no runtime network requests.
-
-Keep writing samples, edit histories, and client text out of public commits unless you hold the rights and a provenance record. A profile is aggregated JSON and can still reveal vocabulary, so store private profiles outside public repositories.
-
-## Documentation
-
-| Read this | When you need |
-| --- | --- |
-| [The Wiki](https://github.com/shashank-sn/holdyourvoice/wiki) | Product and contributor docs. |
-| [Architecture](docs/ARCHITECTURE.md) | Source boundaries and extension rules. |
-| [Prompt contract](docs/PROMPT-CONTRACT.md) | The tier order and editing constraints. |
-| [VoiceDNA](docs/VOICE-DNA.md) | The 13 profile elements. |
-| [Fact linter](docs/wiki/Fact-Linter.md) | The source-consistency checker. |
-| [Support](SUPPORT.md) | Funding without a feature gate. |
+The `skills/hyv-*` directories package the CLI workflows as portable agent contracts. Use `hyv agent validate` to check them and `hyv agent emit` to create a host-specific prompt or JSON contract.
+
+The MCP server exposes the same local engine for compatible hosts. Read [Portable Agents](docs/wiki/Portable-Agents.md), [Claude Desktop setup](docs/CLAUDE-DESKTOP.md), or [Claude Code setup](docs/CLAUDE-CODE.md).
+
+## privacy and safety
 
-## Contribute
+Drafts, samples, profiles, candidates, and source files stay on your machine. The package has no accounts, telemetry, hosted analysis, or runtime network requests.
+
+Learning commands can write text-free events under `~/.hyv/learning/`. A manually added learning instruction is stored as entered. Keep private writing, profiles, and client data out of public repositories.
+
+VoiceDNA fit, AI-pattern findings, fact consistency, and human approval are separate results. A clean report only states that its configured checks passed. Authorship, factual truth, and publication quality still need separate evidence or review.
+
+## development
 
 ```bash
+npm ci
 npm test
 npm run check:release
 ```
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Keep changes narrow, add tests when behavior changes, and keep private or unlicensed material out of the repo.
-
-`@holdyourvoice/hyv` publishes automatically when a change reaches `main`. Bump the version in `package.json` in the same pull request as a release-worthy change; the workflow publishes only if that version is not already on npm.
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The main design boundaries are in [Architecture](docs/ARCHITECTURE.md) and the full user guides are in the [wiki](https://github.com/shashank-sn/holdyourvoice/wiki).
 
-## License
+## license
 
-[MIT](LICENSE). Third-party writing and data retain their own rights.
+[MIT](LICENSE). Third-party writing and data keep their own rights.

package/dist/agents/catalog.js

@@ -0,0 +1,118 @@
+const CATALOG = {
+    generic: {
+        id: 'generic', display_name: 'Generic coding environment', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: false, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: false,
+        context_capacity: 'host-defined', filesystem_mode: 'host-defined', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'portable Markdown instructions and standalone CLI',
+    },
+    codex: {
+        id: 'codex', display_name: 'Codex', native_skills: true, subagents: true,
+        hooks: false, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'sandboxed', network_policy: 'approval-gated',
+        subagent_isolation: true, session_reset: true, structured_output: true,
+        integration: 'native skills with AGENTS.md fallback',
+    },
+    'claude-code': {
+        id: 'claude-code', display_name: 'Claude Code', native_skills: true, subagents: true,
+        hooks: true, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'host-defined', network_policy: 'approval-gated',
+        subagent_isolation: true, session_reset: false, structured_output: true,
+        integration: 'native skills and agent instructions',
+    },
+    cursor: {
+        id: 'cursor', display_name: 'Cursor', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated rules and portable instructions',
+    },
+    copilot: {
+        id: 'copilot', display_name: 'GitHub Copilot', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'repository instructions and custom agent definitions',
+    },
+    'gemini-cli': {
+        id: 'gemini-cli', display_name: 'Gemini CLI', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: true, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'approval-gated',
+        subagent_isolation: false, session_reset: false, structured_output: true,
+        integration: 'terminal-agent instructions and standalone CLI',
+    },
+    'ide-agent': {
+        id: 'ide-agent', display_name: 'IDE coding agent', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated rules or portable instructions',
+    },
+    windsurf: {
+        id: 'windsurf', display_name: 'Windsurf', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+    cline: {
+        id: 'cline', display_name: 'Cline', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+    'roo-code': {
+        id: 'roo-code', display_name: 'Roo Code', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+};
+export function resolveHost(id) {
+    return CATALOG[id] ?? CATALOG.generic;
+}
+export function listHosts() {
+    return Object.values(CATALOG).sort((a, b) => a.id.localeCompare(b.id));
+}
+function hostSupports(host, permission) {
+    switch (permission) {
+        case 'read_repository': return host.repository_read;
+        case 'write_repository': return host.file_edits;
+        case 'execute_commands': return host.command_execution;
+        case 'network': return false;
+        case 'browser_automation': return host.browser_automation;
+        case 'git_write':
+        case 'pull_request_write': return host.command_execution;
+        case 'subagents': return host.subagents;
+        default: return false;
+    }
+}
+export function runtime(agent, hostID) {
+    const host = resolveHost(hostID);
+    const available = [];
+    const unavailable = [];
+    for (const permission of agent.permissions) {
+        if (hostSupports(host, permission))
+            available.push(permission);
+        else
+            unavailable.push({ capability: permission, status: 'NOT_AVAILABLE' });
+    }
+    let mode = 'procedural';
+    if (unavailable.length > 0)
+        mode = 'prompt-only';
+    if (host.native_skills && unavailable.length === 0)
+        mode = 'native';
+    return { agent, host, available_capabilities: available, unavailable_capabilities: unavailable, execution_mode: mode };
+}

package/dist/agents/catalog.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveHost, listHosts, runtime } from './catalog.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function minimalDescriptor(id, permissions) {
+    return {
+        schema_version: AGENT_SCHEMA_VERSION,
+        id,
+        title: id,
+        description: 'test',
+        instruction_file: 'SKILL.md',
+        role: 'Tester',
+        workflow_phase: 'test',
+        input: { required: ['draft'], optional: [] },
+        output: { required: ['report'], optional: [] },
+        evidence_requirements: ['evidence'],
+        permissions,
+        stop_conditions: ['stop'],
+        tool_free_mode: { available: true, behavior: 'report', unavailable_statuses: ['NOT_AVAILABLE'] },
+        handoff_to: [],
+    };
+}
+test('resolves known hosts and falls back to generic for unknown ids', () => {
+    assert.equal(resolveHost('codex').id, 'codex');
+    assert.equal(resolveHost('future-ide').id, 'generic');
+    assert.equal(resolveHost('future-ide').native_skills, false);
+    assert.equal(resolveHost('future-ide').cli, true);
+});
+test('catalog has unique host ids and includes generic', () => {
+    const hosts = listHosts();
+    const ids = hosts.map((host) => host.id);
+    assert.ok(ids.includes('generic'));
+    assert.equal(new Set(ids).size, ids.length);
+});
+test('runtime marks unsupported permissions unavailable and switches to prompt-only', () => {
+    const descriptor = minimalDescriptor('hyv-verify', ['read_repository', 'network', 'subagents']);
+    const resolved = runtime(descriptor, 'generic');
+    assert.deepEqual(resolved.available_capabilities, []);
+    assert.deepEqual(resolved.unavailable_capabilities, [
+        { capability: 'read_repository', status: 'NOT_AVAILABLE' },
+        { capability: 'network', status: 'NOT_AVAILABLE' },
+        { capability: 'subagents', status: 'NOT_AVAILABLE' },
+    ]);
+    assert.equal(resolved.execution_mode, 'prompt-only');
+});
+test('runtime uses native mode when the host supports every permission', () => {
+    const descriptor = minimalDescriptor('hyv-verify', ['read_repository', 'execute_commands']);
+    const resolved = runtime(descriptor, 'codex');
+    assert.deepEqual(resolved.available_capabilities, ['read_repository', 'execute_commands']);
+    assert.deepEqual(resolved.unavailable_capabilities, []);
+    assert.equal(resolved.execution_mode, 'native');
+});
+test('network is never available on any host', () => {
+    for (const host of listHosts()) {
+        const resolved = runtime(minimalDescriptor('hyv-verify', ['network']), host.id);
+        assert.deepEqual(resolved.available_capabilities, []);
+        assert.deepEqual(resolved.unavailable_capabilities, [{ capability: 'network', status: 'NOT_AVAILABLE' }]);
+        assert.equal(resolved.execution_mode, 'prompt-only');
+    }
+});

package/dist/agents/emit.js

@@ -0,0 +1,42 @@
+import { runtime } from './catalog.js';
+export function describe(pkg, hostID) {
+    return runtime(pkg.descriptor, hostID);
+}
+export function emitJson(pkg, hostID) {
+    return JSON.stringify(describe(pkg, hostID), null, 2);
+}
+function printable(values) {
+    return values.length === 0 ? 'none' : values.join(', ');
+}
+function printableUnavailable(values) {
+    return values.length === 0 ? 'none' : values.map(({ capability, status }) => `${capability} (${status})`).join(', ');
+}
+function runtimeSummary(descriptor) {
+    const host = descriptor.host;
+    return `Context capacity: ${host.context_capacity}; filesystem mode: ${host.filesystem_mode}; network policy: ${host.network_policy}; browser/UI: ${host.browser_automation}; subagent isolation: ${host.subagent_isolation}; session reset: ${host.session_reset}; structured output: ${host.structured_output}.`;
+}
+export function emitPrompt(pkg, hostID) {
+    const descriptor = pkg.descriptor;
+    const resolved = describe(pkg, hostID);
+    const lines = [];
+    lines.push(`# ${descriptor.title}`, '');
+    lines.push(`Role: ${descriptor.role}`);
+    lines.push(`Phase: ${descriptor.workflow_phase}`);
+    lines.push(`Execution mode: ${resolved.execution_mode}`, '');
+    lines.push('## Contract', '');
+    lines.push(`Required input: ${printable(descriptor.input.required)}`);
+    lines.push(`Required output: ${printable(descriptor.output.required)}`);
+    lines.push(`Evidence: ${printable(descriptor.evidence_requirements)}`);
+    lines.push(`Stop conditions: ${printable(descriptor.stop_conditions)}`, '');
+    lines.push('## Runtime descriptor', '');
+    lines.push(runtimeSummary(resolved), '');
+    lines.push('## Capability boundary', '');
+    lines.push(`Available: ${printable(resolved.available_capabilities)}`);
+    lines.push(`Unavailable: ${printableUnavailable(resolved.unavailable_capabilities)}`, '');
+    lines.push(`When a capability is unavailable, ${descriptor.tool_free_mode.behavior} Status must be one of: ${printable(descriptor.tool_free_mode.unavailable_statuses)}.`, '');
+    lines.push('## Handoff', '');
+    lines.push(`Next agents: ${printable(descriptor.handoff_to)}`, '');
+    lines.push('## Instructions', '');
+    lines.push(pkg.instructions.trim());
+    return `${lines.join('\n')}\n`;
+}

package/dist/agents/emit.test.js

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { describe, emitJson, emitPrompt } from './emit.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function makePackage(id) {
+    return {
+        directory: '/pkg',
+        instructions: 'Usage: hyv verify original.md candidate.md profile.json',
+        descriptor: {
+            schema_version: AGENT_SCHEMA_VERSION,
+            id,
+            title: 'hyv-verify',
+            description: 'verify a candidate',
+            instruction_file: 'SKILL.md',
+            role: 'Verifier',
+            workflow_phase: 'verify',
+            input: { required: ['original', 'candidate'], optional: ['writing brief'] },
+            output: { required: ['verification report'], optional: [] },
+            evidence_requirements: ['preserve revision evidence'],
+            permissions: ['read_repository', 'network'],
+            stop_conditions: ['stop when evidence is stale'],
+            tool_free_mode: {
+                available: true,
+                behavior: 'report the decision and exact unavailable capability',
+                unavailable_statuses: ['NOT_AVAILABLE', 'NOT_CONFIGURED', 'NOT_RUN', 'STALE', 'ERROR'],
+            },
+            handoff_to: ['hyv-lifecycle'],
+        },
+    };
+}
+test('describe resolves a host and returns a runtime descriptor', () => {
+    const resolved = describe(makePackage('hyv-verify'), 'codex');
+    assert.equal(resolved.agent.id, 'hyv-verify');
+    assert.equal(resolved.host.id, 'codex');
+    assert.ok(resolved.available_capabilities.includes('read_repository'));
+    assert.deepEqual(resolved.unavailable_capabilities, [{ capability: 'network', status: 'NOT_AVAILABLE' }]);
+    assert.equal(resolved.execution_mode, 'prompt-only');
+});
+test('emitJson renders a valid JSON runtime descriptor', () => {
+    const body = emitJson(makePackage('hyv-verify'), 'generic');
+    const parsed = JSON.parse(body);
+    assert.equal(parsed.agent.id, 'hyv-verify');
+    assert.equal(parsed.host.id, 'generic');
+    assert.ok(Array.isArray(parsed.unavailable_capabilities));
+    assert.deepEqual(parsed.unavailable_capabilities, [
+        { capability: 'read_repository', status: 'NOT_AVAILABLE' },
+        { capability: 'network', status: 'NOT_AVAILABLE' },
+    ]);
+});
+test('emitPrompt includes instructions, capability boundary, and required statuses', () => {
+    const prompt = emitPrompt(makePackage('hyv-verify'), 'codex');
+    assert.match(prompt, /# hyv-verify/);
+    assert.match(prompt, /Role: Verifier/);
+    assert.match(prompt, /Usage: hyv verify original\.md candidate\.md profile\.json/);
+    assert.match(prompt, /Available: read_repository/);
+    assert.match(prompt, /Unavailable: network \(NOT_AVAILABLE\)/);
+    assert.match(prompt, /NOT_AVAILABLE, NOT_CONFIGURED, NOT_RUN, STALE, ERROR/);
+    assert.match(prompt, /Next agents: hyv-lifecycle/);
+});
+test('emitPrompt reports no available capabilities for a fully unavailable host', () => {
+    const prompt = emitPrompt(makePackage('hyv-verify'), 'generic');
+    assert.match(prompt, /Available: none/);
+    assert.match(prompt, /Execution mode: prompt-only/);
+});

package/dist/agents/index.js

@@ -0,0 +1,4 @@
+export { AGENT_SCHEMA_VERSION, VALID_PERMISSIONS, VALID_UNAVAILABLE_STATUSES, } from './types.js';
+export { resolveHost, listHosts, runtime } from './catalog.js';
+export { loadAll, loadAllFrom, sortedIds, validateAll, validateId } from './load.js';
+export { describe, emitJson, emitPrompt } from './emit.js';