@aikdna/kdna-cli 0.25.0 → 0.26.0

package/README.md

@@ -2,203 +2,123 @@
 
 [![npm](https://img.shields.io/npm/v/@aikdna/kdna-cli)](https://www.npmjs.com/package/@aikdna/kdna-cli) [![CI](https://github.com/aikdna/kdna-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aikdna/kdna-cli/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-> **KDNA Core v1 is the official KDNA judgment-asset format and runtime loading contract.** `.kdna` assets are created, inspected, packed, unpacked, and validated through the **official KDNA toolchain**.
+The official command-line runtime for KDNA Core v1 judgment assets.
 
-**Role**: kdna-cli is the **official KDNA runtime CLI** — the official command-line entry point of the KDNA toolchain for inspecting, validating, packing, unpacking, and loading `.kdna` assets.
+KDNA CLI inspects, validates, packs, unpacks, and loads `.kdna` files. It is
+the consumer/runtime side of the official KDNA toolchain. Formal authoring is
+handled by KDNA Studio CLI and Studio Core.
 
-**KDNA CLI is the official CLI entry of the KDNA toolchain — the official command-line surface for `.kdna` asset operations.**
+KDNA Core v1 does not require a public registry, marketplace, quality badge, or
+signature system. The current first-run path uses local `.kdna` files.
 
-Third-party products integrate KDNA through the official SDK, CLI, Loader, or API.
-
-KDNA CLI 是 KDNA 官方工具链的 CLI 入口,是 `.kdna` 资产操作的官方命令行界面。第三方产品通过官方 SDK、CLI、Loader 或 API 接入 KDNA。
-
-The CLI is how a `.kdna` judgment asset becomes usable by agents. It inspects, validates, packs, unpacks, and loads KDNA assets, and records traces for audit.
-
-KDNA CLI 让一个领域判断资产真正被 Agent 使用。它负责安装 KDNA、验证结构与信任信息、把 KDNA 转换成 Agent 可加载的形式、对比加载前后的判断路径，并记录可审计的使用痕迹。
-
-A `.kdna` asset is not created by writing JSON files. It is compiled by a
-Studio-compatible authoring pipeline that performs human confirmation,
-validation, canonicalization, identity generation, digest computation, signing,
-optional encryption, and provenance recording. kdna-cli verifies and publishes
-existing assets; it does not author trusted KDNA.
-
-Part of the [KDNA](https://github.com/aikdna/kdna) ecosystem.
+Authorization and runtime-load decisions are defined in `aikdna/kdna`, not in
+this repository. `kdna plan-load` is the CLI diagnostic surface for that
+contract and MUST call the LoadPlan API from `@aikdna/kdna-core` instead of
+deriving authorization state directly from manifest fields.
 
 ## Install
 
 ```bash
 npm install -g @aikdna/kdna-cli
-kdna setup
 ```
 
-## Quick Start (5 minutes)
+## 5-Minute Path
 
 ```bash
-npm install -g @aikdna/kdna-cli
-kdna setup
-kdna install @aikdna/writing
-kdna verify @aikdna/writing --judgment
-kdna compare @aikdna/writing --input "help me improve this post"
-kdna doctor --agents
+kdna demo minimal ./minimal
+kdna inspect ./minimal
+kdna validate ./minimal
+kdna plan-load ./minimal --json
+kdna pack ./minimal ./minimal.kdna
+kdna validate ./minimal.kdna
+kdna load ./minimal.kdna --profile=compact --as=prompt
 ```
 
-## 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
-
-### Dev Source Utilities
-
-| Command                            | Status       | Description                                                                 |
-| ---------------------------------- | ------------ | --------------------------------------------------------------------------- |
-| `kdna init <name>`                 | Deprecated   | Alias for `kdna dev scaffold`; creates a non-canonical dev source workspace |
-| `kdna dev scaffold <name>`         | Beta         | Scaffold a non-canonical dev source workspace                               |
-| `kdna dev validate <path>`         | Stable       | Validate a non-canonical dev source directory                               |
-| `kdna dev pack <path>`             | Beta         | Build a dev-only non-trusted `.kdna` bundle                                 |
-| `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 <file.kdna>`         | Experimental | Publish an existing Studio-compiled `.kdna` asset                           |
-| `kdna publish --check <path>`      | Experimental | Dev source readiness check only; does not publish                           |
-| `kdna version bump <level> [path]` | Beta         | Bump domain version                                                         |
-
-### Agent Runtime
-
-| 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                                                      | 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                           | 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
-
-Licensed asset loading (`kdna install`, `kdna load`, `kdna verify`) requires a
-valid local activation. Full RFC-0008 conformance across JS Core, Swift Core,
-and CLI is tracked via cross-language test vectors in the
-[kdna](https://github.com/aikdna/kdna) conformance suite.
-
-| 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                    | Status  | Description               |
-| -------------------------- | ------- | ------------------------- |
-| `kdna cluster lint <path>` | Planned | Validate cluster manifest |
-
-### Registry & Distribution
-
-| 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                        | 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      | Status | Description                                |
-| ------------ | ------ | ------------------------------------------ |
-| `kdna setup` | Beta   | One-command setup: CLI + skill + data root |
-
----
-
-## SPEC Compatibility
-
-KDNA CLI follows the canonical KDNA Container format defined in [`aikdna/kdna`](https://github.com/aikdna/kdna).
-
-A valid KDNA asset is a `.kdna` container with:
-- `kdna.json` — public manifest and metadata (no judgment content)
-- `payload.kdnab` — CBOR-encoded judgment payload
-- `signature.kdsig` — Ed25519 signature
+Successful validation returns:
+
+```json
+{
+  "format_valid": true,
+  "schema_valid": true,
+  "payload_valid": true,
+  "checksums_valid": true,
+  "load_contract_valid": true,
+  "overall_valid": true,
+  "problems": []
+}
+```
 
-The authoring source tree uses standard JSON files (KDNA_Core.json, KDNA_Patterns.json, etc.) for human editing and Git review. These files belong to the source tree only and MUST NOT appear as top-level entries in a distribution `.kdna` asset.
+## Core Commands
 
-To create a trusted `.kdna`, use `kdna-studio migrate <source-dir> --out <file.kdna>` or a Studio-compatible compiler that records authoring provenance, Human Lock evidence, compiler metadata, and asset digest.
+| Command | Purpose |
+|---|---|
+| `kdna demo minimal <dir>` | Create a minimal v1 source directory |
+| `kdna inspect <path>` | Inspect a v1 source dir or `.kdna` container |
+| `kdna validate <path>` | Validate format, schema, payload, checksums, and load contract |
+| `kdna plan-load <path> --json` | Return the Core LoadPlan before runtime load |
+| `kdna plan-load <path> --json --has-password` | Diagnose password-authorized load state |
+| `kdna plan-load <path> --json --entitlement-status active` | Diagnose receipt/entitlement load state |
+| `kdna pack <source-dir> <output.kdna>` | Pack a v1 source directory |
+| `kdna unpack <input.kdna> <output-dir>` | Unpack a v1 container |
+| `kdna load <path> --profile=<index|compact|scenario|full> --as=<json|prompt>` | Render judgment context for agents or tools |
+| `kdna setup` | Install the `kdna-loader` skill for supported agents |
+| `kdna doctor --agents` | Check agent loader installation |
 
----
+## Producer Path
 
-## Legacy Registry (deprecated)
+Use Studio CLI to create formal v1 `.kdna` assets:
 
-KDNA Core v1 is the **official KDNA judgment-asset format**. KDNA Core v1 does not define a registry, marketplace, or quality-badge system. Assets are loaded by path or by the official CLI, not by registry name.
+```bash
+npm install -g @aikdna/kdna-studio-cli
+kdna-studio create my_domain --name @yourscope/my_domain
+kdna-studio migrate ./my_domain --format v1 --out ./my_domain.kdna
+kdna validate ./my_domain.kdna
+kdna load ./my_domain.kdna --profile=compact --as=prompt
+```
 
-The legacy `kdna install <name>` command and the `KDNA_REGISTRY_URL` env var are preserved for backward compatibility with the legacy `kdna-registry` repository (marked as a legacy experiment). New KDNA Core v1 integrations should use the official CLI route:
+## Legacy Compatibility
 
-```bash
-kdna inspect <path>
-kdna validate <path>
-kdna pack <source-dir> <output.kdna>
-kdna unpack <input.kdna> <output-dir>
+Older CLI commands for registry install, compare, trace, licensing, identity, or
+pre-v1 dev source workflows may still exist for backward compatibility. They
+are not the KDNA Core v1 launch path.
+
+New integrations should use the v1 Core route:
+
+```text
+source or Studio project
+→ v1 .kdna container
+→ kdna validate
+→ kdna plan-load
+→ kdna load
+→ agent/runtime context
 ```
 
----
+## Runtime Authorization Contract
+
+The source of truth is `aikdna/kdna`:
 
-## Official toolchain components
+- `specs/kdna-authorization-contract.md`
+- `schema/load-plan.schema.json`
+- `conformance/authorization/cases.json`
+- `conformance/authorization/goldens/*.loadplan.json`
 
-KDNA Core v1 is the **official KDNA judgment-asset format**. `.kdna` assets are created, inspected, protected, loaded, and consumed through the official KDNA toolchain. Third-party products integrate KDNA through the official SDK, CLI, Loader, or API.
+This CLI is a diagnostic control plane. It may display, validate, and transport
+LoadPlan results, but it must not define access modes, entitlement profiles,
+issue codes, crypto profiles, or fail-closed policy independently.
+
+Current local authorization path:
+
+```bash
+kdna validate ./asset.kdna --json
+kdna plan-load ./asset.kdna --json
+kdna plan-load ./asset.kdna --json --has-password
+kdna plan-load ./asset.kdna --json --entitlement-status active
+kdna load ./asset.kdna --profile=compact --as=prompt
+```
 
-| Layer | Component | Responsibility |
-| ------ | -------------------------- | --------------- |
-| Format | KDNA Core | Official KDNA judgment-asset format and runtime loading contract |
-| Core Library | @aikdna/kdna-core | Official loader SDK |
-| Runtime | @aikdna/kdna-cli | Official CLI: inspect, validate, pack, unpack, load |
-| Authoring | KDNA Studio Core | Official authoring kernel |
+`plan-load` requires a version of `@aikdna/kdna-core` that exports the LoadPlan
+v1 API. Until that dependency is released and installed, the command fails with
+a version-gate error instead of falling back to duplicated CLI-side parsing.
 
 ## Development
 
@@ -211,9 +131,10 @@ npm test
 
 ## Related
 
-- [@aikdna/kdna-core](https://github.com/aikdna/kdna/tree/main/packages/kdna-core) — Official loader SDK
-- [KDNA SPEC](https://github.com/aikdna/kdna) — Official KDNA Core format
-- [aikdna.com](https://aikdna.com) — Website
+- [KDNA Core](https://github.com/aikdna/kdna/tree/main/packages/kdna-core)
+- [KDNA Studio CLI](https://github.com/aikdna/kdna-studio-cli)
+- [KDNA Skills](https://github.com/aikdna/kdna-skills)
+- [aikdna.com](https://aikdna.com)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "KDNA CLI — runtime control plane for verifying, installing, loading, comparing, publishing, and auditing existing .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -55,7 +55,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "^0.11.0"
+    "@aikdna/kdna-core": "^0.12.0"
   },
   "optionalDependencies": {
     "ajv": "^8.20.0",

package/src/cli.js

@@ -61,6 +61,10 @@ if (!args.length || args[0] === '--help' || args[0] === '-h') {
   showHelp();
   process.exit(0);
 }
+if (args[0] === '--version' || args[0] === '-v') {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
 if (args[0] === 'help') {
   const sub = args[1];
   if (sub === 'advanced' || sub === 'legacy') {
@@ -85,6 +89,8 @@ Start here:
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path>                  Return a LoadPlan before runtime load
+                                  Add --has-password or --entitlement-status for diagnostics
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
 
@@ -105,6 +111,8 @@ function showHelpAdvanced() {
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path> [--has-password] [--entitlement-status <status>]
+                                  Return a LoadPlan before runtime load
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
   demo     minimal <dir> [--force]  Create a minimal v1 fixture
@@ -138,7 +146,7 @@ function showHelpLegacy() {
 Not part of the current KDNA Core v1 first-run path. Preserved for
 backward compatibility. These commands may change or be removed.
 
-Registry (legacy — kdna-registry is a legacy experiment):
+Registry (legacy compatibility — not a Core v1 public path):
   install <name>                    Install domain from legacy registry
   remove <name>                     Uninstall a domain
   update <name>                     Update installed domain
@@ -267,6 +275,33 @@ switch (cmd) {
     );
     break;
   }
+  case 'plan-load': {
+    const v1Target = args.filter((a) => !a.startsWith('--'))[1];
+    if (!v1Target) error('Usage: kdna plan-load <path> [--json] [--has-password] [--entitlement-status <status>]', EXIT.INPUT_ERROR);
+    const core = require('@aikdna/kdna-core');
+    const abs = require('node:path').resolve(v1Target);
+    if (!(core.isV1SourceDir(abs) || core.detectContainerFormat(abs) === 'v1')) {
+      error('plan-load requires a KDNA Core v1 source dir or .kdna container', EXIT.INPUT_ERROR);
+    }
+    if (typeof core.planLoad !== 'function') {
+      error(
+        'kdna plan-load requires @aikdna/kdna-core with the LoadPlan v1 API. Update @aikdna/kdna-core before enabling runtime authorization diagnostics.',
+        EXIT.PROVIDER_ERROR,
+      );
+    }
+    const entitlementStatusIndex = args.indexOf('--entitlement-status');
+    const entitlementStatus = entitlementStatusIndex >= 0 ? args[entitlementStatusIndex + 1] : null;
+    const allowedEntitlementStatuses = new Set(['active', 'expired', 'revoked', 'offline_grace']);
+    if (entitlementStatusIndex >= 0 && !allowedEntitlementStatuses.has(entitlementStatus)) {
+      error('Invalid --entitlement-status. Use active, expired, revoked, or offline_grace.', EXIT.INPUT_ERROR);
+    }
+    const plan = core.planLoad(v1Target, {
+      hasPassword: args.includes('--has-password'),
+      entitlement: entitlementStatus ? { status: entitlementStatus } : undefined,
+    });
+    console.log(JSON.stringify(plan, null, 2));
+    process.exit(plan.state === 'invalid' ? 1 : 0);
+  }
   case 'pack': {
     const v1Target = args.filter((a) => !a.startsWith('--'))[1];
     if (v1Target) {

package/src/publish.js

@@ -689,12 +689,12 @@ function cmdPublish(assetPath, args = []) {
 
   console.log('');
   console.log('─'.repeat(60));
-  console.log('Registry patch (apply to kdna-registry/domains.json):');
+  console.log('Legacy registry patch (historical compatibility only):');
   console.log('─'.repeat(60));
   console.log(JSON.stringify(patch, null, 2));
   console.log('');
   console.log(
-    `Next: open a PR to kdna-registry merging this patch into the matching entry by "name".`,
+    `Next: do not open a public registry PR. Core v1 publishes local .kdna files through validate/load evidence, not a central registry.`,
   );
 }
 

package/templates/standard-domain/USAGE.md

@@ -43,18 +43,15 @@ kdna identity init
 # 6. Verify quality
 kdna verify ./.
 
-# 7. Publish
+# 7. Export and verify the local v1 asset
 KDNA_IDENTITY_DIR=~/.kdna/identity-official \
-  # Trusted publish starts from a Studio-compiled .kdna asset.
-  kdna publish ./dist/your-domain.kdna \
-    --release-tag v0.1.0 \
-    --repo yourname/kdna-<your_domain_id>
+  kdna validate ./dist/your-domain.kdna
 
-# 8. Open PR to kdna-registry with the patch JSON the command printed
+kdna load ./dist/your-domain.kdna --profile=compact --as=prompt
 ```
 
 ## Standard vs minimal-domain
 
 `minimal-domain/` is the **bare-minimum** template — 2 files, no v2.1 fields, no evals. Use it only for fast experimentation or learning.
 
-`standard-domain/` is the **registry-ready** template. Any domain meant to be published to the registry should start here and aim for `kdna verify --judgment` ≥ 80% before publishing.
+`standard-domain/` is the richer authoring template for domains that need evidence, limitations, and repeatable validation. Core v1 distribution is local `.kdna` export plus `kdna validate` / `kdna load` evidence, not a central registry submission.