@aikdna/kdna-cli 0.16.10 → 0.18.0

package/README.md

@@ -1,10 +1,20 @@
 # @aikdna/kdna-cli
 
-**KDNA CLI is the runtime control plane for loading, validating, composing, testing, and governing domain judgment for AI agents.**
+> **KDNA Ecosystem:** [`kdna`](https://github.com/aikdna/kdna) — the protocol. [KDNAChat](https://github.com/AhaSparkCoach/kdnachat) — the consumption client. [KDNaStudio](https://github.com/AhaSparkCoach/kdnastudio) — the authoring tool. [KDNAWork](https://github.com/AhaSparkCoach/kdnawork) — the workbench. **You are here → kdna-cli** — the toolchain. [Registry](https://github.com/aikdna/kdna-registry) — the catalog.
 
-KDNA CLI 是 AI Agent 加载、验证、组合、测试和治理领域判断的运行控制平面。
+**Role**: kdna-cli is the **runtime control plane** — the official reference implementation for domain validation, loading, packaging, comparison, and agent-facing runtime workflows. It bridges Studio output to Chat/Work consumption.
 
-Part of the [KDNA](https://github.com/aikdna/KDNA) ecosystem.
+**KDNA CLI is the official open-source reference implementation for KDNA validation, loading, packaging, comparison, registry access, and agent-facing runtime workflows.**
+
+It is the runtime control plane for loading, validating, composing, testing, and governing domain judgment for AI agents.
+
+KDNA CLI 是 KDNA 验证、加载、打包、比较、注册表访问和 Agent 运行时工作流的官方开源参考实现，也是 AI Agent 加载、验证、组合、测试和治理领域判断的运行控制平面。
+
+The CLI is how a KDNA domain judgment package becomes usable by agents. It installs KDNA domains, verifies their structure and trust metadata, loads them into agent-readable form, compares judgment paths with and without KDNA, and records traces for audit.
+
+KDNA CLI 让一个领域判断资产真正被 Agent 使用。它负责安装 KDNA、验证结构与信任信息、把 KDNA 转换成 Agent 可加载的形式、对比加载前后的判断路径，并记录可审计的使用痕迹。
+
+Part of the [KDNA](https://github.com/aikdna/kdna) ecosystem.
 
 ## Install
 
@@ -24,103 +34,176 @@ kdna compare @aikdna/writing --input "help me improve this post"
 kdna doctor --agents
 ```
 
-## Commands by Role
+## The 6 Commands You Actually Need
+
+| Command | What it does |
+|---------|-------------|
+| `kdna setup` | Initialize ~/.kdna, install the agent skill loader |
+| `kdna install <domain>` | Install a domain from the registry |
+| `kdna list` | Show installed domains with quality info |
+| `kdna verify <domain>` | 3-layer check: structure + trust + judgment |
+| `kdna compare <domain> --input "..."` | Compare with/without KDNA judgment |
+| `kdna doctor --agents` | Check agent integration health |
+
+## All Commands by Role
 
 ### Domain Authoring
 
-| Command | Description |
-|---------|-------------|
-| `kdna init <name>` | Scaffold a new domain from template |
-| `kdna validate <path>` | Validate domain structure |
-| `kdna validate --schema <path>` | Schema-only validation |
-| `kdna pack <path>` | Pack into .kdna container |
-| `kdna pack <path> --encrypt --license <file>` | Pack encrypted .kdnae container |
-| `kdna unpack <file>` | Unpack .kdna or .kdnae container |
-| `kdna inspect <path>` | Inspect domain or .kdna file |
-| `kdna publish <path>` | Pack + sign + publish to registry |
-| `kdna publish --check <path>` | Quality gate check only |
-| `kdna version bump <level> [path]` | Bump domain version |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna init <name>` | Beta | Scaffold a new domain from template |
+| `kdna dev validate <path>` | Stable | Validate a non-canonical dev source directory |
+| `kdna dev pack <path>` | Beta | Build a dev source directory into a .kdna asset |
+| `kdna dev unpack <file>` | Beta | Unpack .kdna into a dev source directory |
+| `kdna dev inspect <path>` | Beta | Inspect a non-canonical dev source directory |
+| `kdna dev card <path>` | Beta | Display KDNA Card from a dev source directory |
+| `kdna inspect <file.kdna>` | Beta | Inspect a .kdna asset |
+| `kdna publish <path>` | Experimental | Pack + sign + publish to registry |
+| `kdna publish --check <path>` | Experimental | Quality gate check only |
+| `kdna version bump <level> [path]` | Beta | Bump domain version |
 
 ### Agent Runtime
 
-| Command | Description |
-|---------|-------------|
-| `kdna available [--json]` | List installed domains with v2.1 fields |
-| `kdna match "<task>" [--json]` | Signal matching — find relevant domains |
-| `kdna load <name> [--as=prompt\|json\|raw]` | Emit domain in agent-ready format |
-| `kdna postvalidate <name> --output <file>` | Post-generation judgment check |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna available [--json]` | Beta | List installed domains with v2.1 fields |
+| `kdna match "<task>" [--json]` | Beta | Signal matching — find relevant domains |
+| `kdna load <name\|file.kdna> [--as=prompt\|json\|raw]` | Beta | Emit asset in agent-ready format |
+| `kdna postvalidate <name> --output <file>` | Beta | Post-generation judgment check |
 
 ### Testing & Verification
 
-| Command | Description |
-|---------|-------------|
-| `kdna verify <name>` | 3-layer: structure + trust + judgment |
-| `kdna compare <name> --input "..."` | With/without KDNA reasoning diff |
-| `kdna compare <name> --input "..." --report-md` | Markdown report with scoring |
-| `kdna compare <name> --input "..." --report-json` | JSON report with scoring |
-| `kdna diff <name>@<v1> <name>@<v2>` | Judgment-level diff between versions |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna verify <name\|file.kdna>` | Beta | 3-layer: structure + trust + judgment |
+| `kdna compare <name\|file.kdna> --input "..."` | Beta | With/without KDNA reasoning diff |
+| `kdna compare <name\|file.kdna> --input "..." --report-md` | Beta | Markdown report with scoring |
+| `kdna compare <name\|file.kdna> --input "..." --report-json` | Beta | JSON report with scoring |
+| `kdna diff <name>@<v1> <name>@<v2>` | Beta | Judgment-level diff between versions |
 
 ### Diagnostics & Trace
 
-| Command | Description |
-|---------|-------------|
-| `kdna doctor` | System health check |
-| `kdna doctor --agents` | Agent integration check (Codex/Claude/OpenCode/Cursor/Gemini) |
-| `kdna doctor --json` | Machine-readable health report |
-| `kdna trace` | View recent load/postvalidate traces |
-| `kdna trace --json` | Machine-readable trace output |
-| `kdna trace --export <file>` | Export traces for audit |
-| `kdna trace --since 7d\|30d\|90d` | Filter by time range |
-| `kdna history` | Recent domain usage (last 20) |
-| `kdna history --stats` | Aggregate by domain and agent |
-| `kdna history --domain <name>` | Filter by domain |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna doctor` | Beta | System health check |
+| `kdna doctor --agents` | Beta | Agent integration check (Codex/Claude/OpenCode/Cursor/Gemini) |
+| `kdna doctor --json` | Beta | Machine-readable health report |
+| `kdna trace` | Experimental | View recent load/postvalidate traces |
+| `kdna trace --json` | Experimental | Machine-readable trace output |
+| `kdna trace --export <file>` | Experimental | Export traces for audit |
+| `kdna trace --since 7d\|30d\|90d` | Experimental | Filter by time range |
+| `kdna history` | Experimental | Recent domain usage (last 20) |
+| `kdna history --stats` | Experimental | Aggregate by domain and agent |
+| `kdna history --domain <name>` | Experimental | Filter by domain |
 
 ### License & Authorization
 
-| Command | Description |
-|---------|-------------|
-| `kdna license generate <domain> --to <email>` | Generate signed license |
-| `kdna license install <license.json>` | Register license for auto-decrypt |
-| `kdna license verify <license.json>` | Verify license signature and validity |
-| `kdna license bind <license.json>` | Bind license to this machine |
-| `kdna license show <license.json>` | Display license details |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna license generate <domain> --to <email>` | Experimental | Generate signed license |
+| `kdna license install <license.json>` | Experimental | Register license for auto-decrypt |
+| `kdna license activate <domain> --key <key> --server <url>` | Experimental | Activate a license from entitlement source |
+| `kdna license sync [domain] [--server <url>]` | Experimental | Refresh entitlement and revocation status |
+| `kdna license verify <license.json>` | Experimental | Verify license signature and validity |
+| `kdna license bind <license.json>` | Experimental | Bind license to this machine |
+| `kdna license show <license.json>` | Experimental | Display license details |
+| `kdna license status [domain] [--json]` | Experimental | Show installed license activation status without exposing keys |
 
 ### Cluster Composition
 
-| Command | Description |
-|---------|-------------|
-| `kdna cluster lint <path>` | Validate cluster manifest |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna cluster lint <path>` | Planned | Validate cluster manifest |
 
 ### Registry & Distribution
 
-| Command | Description |
-|---------|-------------|
-| `kdna install <name>` | Install domain from registry |
-| `kdna install ./file.kdna` | Install from local .kdna file |
-| `kdna install ./file.kdnae` | Install from encrypted .kdnae (auto-decrypt with license) |
-| `kdna remove <name>` | Uninstall a domain |
-| `kdna update <name>` | Update installed domain |
-| `kdna info <name>` | Show domain metadata and trust status |
-| `kdna list [--available]` | List installed or available domains |
-| `kdna search <keyword>` | Search registry |
-| `kdna registry refresh` | Refresh registry cache |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna install <name>` | Beta | Install domain from registry |
+| `kdna install file.kdna` | Beta | Install from local .kdna asset |
+| `kdna remove <name>` | Beta | Uninstall a domain |
+| `kdna update <name>` | Beta | Update installed domain |
+| `kdna info <name>` | Beta | Show domain metadata and trust status |
+| `kdna list [--available]` | Beta | List installed or available domains |
+| `kdna search <keyword>` | Beta | Search registry |
+| `kdna registry refresh` | Beta | Refresh registry cache |
 
 ### Identity & Signing
 
-| Command | Description |
-|---------|-------------|
-| `kdna identity init` | Generate Ed25519 signing key |
-| `kdna identity show` | Display public key and buyer ID |
-| `kdna identity export [--out]` | Backup private key (encrypted) |
-| `kdna identity import <file>` | Restore identity from backup |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna identity init` | Experimental | Generate Ed25519 signing key |
+| `kdna identity show` | Experimental | Display public key and buyer ID |
+| `kdna identity export [--out]` | Experimental | Backup private key (encrypted) |
+| `kdna identity import <file>` | Experimental | Restore identity from backup |
 
 ### Setup
 
-| Command | Description |
-|---------|-------------|
-| `kdna setup` | One-command setup: CLI + skill + data root |
+| Command | Status | Description |
+|---------|--------|-------------|
+| `kdna setup` | Beta | One-command setup: CLI + skill + data root |
+
+---
+
+## SPEC Compatibility
+
+KDNA CLI follows the canonical KDNA asset structure defined in [`aikdna/kdna`](https://github.com/aikdna/kdna).
+
+A valid KDNA domain is a `.kdna` asset. The internal tree of that asset may include up to six standard KDNA judgment files:
+
+- `KDNA_Core.json`
+- `KDNA_Patterns.json`
+- `KDNA_Scenarios.json`
+- `KDNA_Cases.json`
+- `KDNA_Reasoning.json`
+- `KDNA_Evolution.json`
+
+The minimum valid `.kdna` asset requires these internal entries:
+
+- `KDNA_Core.json`
+- `KDNA_Patterns.json`
+
+Each KDNA judgment file must include `meta.version`, `meta.domain`, `meta.created`, `meta.purpose`, and `meta.load_condition`.
+
+Source directories are dev-only authoring workspaces. Public install, inspect, verify, load, compare, and agent-facing commands consume `.kdna` assets or installed asset names, not source directories.
+
+---
+
+## Default Registry
+
+By default, KDNA CLI uses the official KDNA registry. Registry schema v3 is asset-first: installable entries must publish `asset_url`, `asset_digest`, signature metadata, trust snapshot/timestamp metadata, and revocations. Expired, yanked, revoked, or digest-mismatched assets are rejected. Users may override the registry with `KDNA_REGISTRY_URL`.
+
+```bash
+# Use the official registry (default)
+kdna install @aikdna/writing
+
+# Use a custom registry
+export KDNA_REGISTRY_URL="https://my-registry.example.com/domains.json"
+kdna install @myorg/internal
+```
+
+---
+
+## Open Source and Commercial Boundary
+
+KDNA keeps the protocol, schemas, validator, core CLI, benchmark tools, and reference examples open source.
+
+Commercial or hosted layers may include:
+
+- Managed registry services
+- Quality badge review workflows
+- Hosted runtime guard
+- Enterprise private registry
+- Team collaboration in KDNA Studio
+- Licensed/private judgment asset distribution
+
+KDNA supports both open judgment assets and licensed/private judgment assets. Open assets remain the default path for community adoption. Licensed assets still use the `.kdna` extension; protected entries are decrypted only in memory after local license activation.
+
+KDNA 同时支持开放判断资产和授权/私有判断资产。开放资产是社区采用的默认路径；授权资产仍然使用 `.kdna` 后缀，受保护条目只会在本地 license activation 通过后以内存方式解密。
+
+---
 
-### Environment Variables
+## Environment Variables
 
 | Variable | Purpose |
 |----------|---------|
@@ -165,7 +248,7 @@ kdna license verify --json <file>
 | Authoring | KDNA Studio | Human-led judgment production |
 | Consumption | KDNAChat | Load, use, compare |
 | Governance | KDNA Governance Console | Approve, release, audit |
-| Distribution | Registry | Discover, install, trade |
+| Distribution | Registry | Discover, install, license, distribute |
 
 ## Development
 
@@ -178,9 +261,9 @@ npm test
 
 ## Related
 
-- [@aikdna/kdna-core](https://github.com/aikdna/KDNA/tree/main/packages/kdna-core) — Pure logic library
+- [@aikdna/kdna-core](https://github.com/aikdna/kdna/tree/main/packages/kdna-core) — Pure logic library
 - [KDNA Registry](https://github.com/aikdna/kdna-registry) — Domain catalog
-- [KDNA SPEC](https://github.com/aikdna/KDNA) — Protocol specification
+- [KDNA SPEC](https://github.com/aikdna/kdna) — Protocol specification
 - [aikdna.com](https://aikdna.com) — Website
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.16.10",
-  "description": "KDNA CLI — create, validate, install, and manage domain cognition packages for AI agents.",
+  "version": "0.18.0",
+  "description": "KDNA CLI — create, validate, install, and manage domain judgment packages for AI agents.",
   "type": "commonjs",
   "bin": {
     "kdna": "src/cli.js",
@@ -30,8 +30,8 @@
     "kdna",
     "kdna-cli",
     "ai-agent",
-    "domain-cognition",
-    "knowledge-dna",
+    "domain-judgment",
+    "judgment-protocol",
     "cli"
   ],
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "^0.3.0"
+    "@aikdna/kdna-core": "^0.5.0"
   },
   "optionalDependencies": {
     "ajv": "^8.17.1",

package/skills/kdna-loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kdna-loader
-description: Discover and load KDNA judgment frameworks from ~/.kdna/domains/ when the task requires domain-specific judgment (review, diagnosis, critique, classification, strategy) where the same input could legitimately be interpreted multiple ways. Skip for pure formatting, factual lookup, code execution, or mechanical transformations. This skill is the entire interface to KDNA — domains themselves are not separate skills.
+description: Discover and load KDNA judgment frameworks from installed .kdna assets when the task requires domain-specific judgment (review, diagnosis, critique, classification, strategy) where the same input could legitimately be interpreted multiple ways. Skip for pure formatting, factual lookup, code execution, or mechanical transformations. This skill is the entire interface to KDNA — domains themselves are not separate skills.
 ---
 
 # KDNA Loader
@@ -17,7 +17,7 @@ this skill provides the **routing and protocol**, KDNA provides the
 **judgment material**.
 
 This skill is the **only** KDNA-related skill. Domains themselves are
-not registered as skills — they live in `~/.kdna/domains/` as data and
+not registered as skills — they live as `.kdna` assets under `~/.kdna/packages/` and
 are discovered on demand. Whether the user has 1 domain installed or
 100, this skill is the single entry point.
 
@@ -68,8 +68,8 @@ Returns a compact JSON array — one entry per installed domain — with:
 axioms), `does_not_apply_when` (flattened), `failure_risks`. Yanked
 domains are excluded automatically.
 
-This is your **only** discovery interface. Do not `ls ~/.kdna/domains/`
-or `cat` the JSON files directly — the CLI is the supported contract
+This is your **only** discovery interface. Do not inspect `~/.kdna/packages/` manually, unzip `.kdna` files,
+or `cat` internal JSON entries directly — the CLI is the supported contract
 between this skill and the KDNA file format. The on-disk layout may
 change; `kdna available` will not.
 
@@ -291,8 +291,7 @@ Otherwise, stay silent about the loading mechanics.
 
 ## What this skill is NOT
 
-- Not a list of available KDNA domains (those live in
-  `~/.kdna/domains/`, discovered on demand)
+- Not a list of available KDNA domains (those are installed `.kdna` assets, discovered on demand)
 - Not a registry browser (use `kdna list --available` CLI)
 - Not a domain creator (use `kdna init <name>` CLI)
 - Not an auto-loader that runs on every request — you decide per