@aikdna/kdna-studio-cli 0.10.2 → 0.13.0-rc.components.2

package/README.md

@@ -1,184 +1,64 @@
-# @aikdna/kdna-studio-cli
+# KDNA Studio CLI — typed current creation
 
-Official Studio command-line entry for KDNA judgment asset creation — turns your notes, documents, works, and feedback into loadable `.kdna` files.
+The terminal Host consumes Studio 4.0.0-rc.components.2, Core 0.37.1-rc.browser.1 and Read 0.11.2-rc.browser.1. Ordinary prose and supported mechanism structures share container `0.5.0` / Read grammar `0.6.4`. Core/Read package versions identify implementation bytes and do not establish interchange with NativeSections container `0.6.0` / Read `0.7.0`, or import/reuse of another CLI's output. Installation acceptance is a separate Host decision; exact content checks do not authenticate a provider process.
 
-Two authoring paths: interview-first (articulate judgment directly) and distillation-first (provide content, find the patterns, review what belongs in scope).
+An external Agent records materials and proposes judgment groups with at least two meaningful alternatives. Selection and final adoption arrive through a separately owned live channel. Human-declared review and expressly delegated Agent editorial adoption are distinct modes:
 
-Distillation-first authoring is domain-first: declare the target domain, owner scope, granularity, task scope, include areas, exclude areas, and load condition before extracting candidates. A single `.kdna` should stay scoped; complex work should compose multiple domain assets through a KDNA Cluster.
-
-This package provides the `kdna-studio` command. It creates Studio projects,
-imports evidence, manages judgment cards, records optional review/provenance
-signals, compiles project content, and exports canonical `.kdna`
-assets with build reports.
-
-It is intentionally separate from `@aikdna/kdna-cli`:
-
-| Package | Command | Role |
-| --- | --- | --- |
-| `@aikdna/kdna-cli` | `kdna` | Runtime CLI: inspect, validate, plan-load, load, pack, and unpack `.kdna` assets |
-| `@aikdna/kdna-studio-cli` | `kdna-studio` | Authoring CLI: create, review, compile, and export `.kdna` files |
-| `@aikdna/kdna-studio-core` | none | Studio SDK/compiler kernel used by apps and this CLI |
-
-## Install
-
-```bash
-npm install -g @aikdna/kdna-studio-cli
+```text
+kdna-studio session --text ./notes.md --out ./new-export --human-fd 3
+kdna-studio session --text ./notes.md --out ./new-export --agent-adoption-fd 3 --delegation-record ./delegation.json
 ```
 
-## Usage
-
-```bash
-kdna-studio create my_domain --name @yourscope/my_domain
-kdna-studio import my_domain ./notes.md
-kdna-studio target declare my_domain \
-  --category expression_writing \
-  --scope personal \
-  --granularity core_principles \
-  --task "longform article review" \
-  --include "argument structure,tone,revision" \
-  --exclude "life habits,food preference"
-kdna-studio source my_domain
-kdna-studio distill my_domain --candidates candidates.json
-kdna-studio candidate list my_domain
-kdna-studio candidate accept my_domain <candidate-id>
-kdna-studio candidate promote my_domain
-kdna-studio card add my_domain axiom \
-  --field one_sentence="Prefer specific evidence over broad claims" \
-  --field full_statement="When reviewing content, prefer specific evidence over broad claims because unsupported generalizations make the judgment impossible to verify or improve." \
-  --field why="Broad claims hide the actual reason for a judgment, so reviewers cannot tell whether the conclusion is evidence based, reusable, or merely plausible sounding." \
-  --field applies_when='["reviewing content"]' \
-  --field does_not_apply_when='["pure formatting"]' \
-  --field failure_risk="generic advice" \
-  --field confidence='high' \
-  --field evidence_type='practice'
-# Optional: record review provenance
-kdna-studio card approve my_domain --all --by expert --statement "I confirm this judgment."
-kdna-studio export my_domain --out dist/my_domain.kdna
-```
+The second mode requires an explicitly supplied JSON record `{ "coordinate": "…", "statement": "…" }` describing existing authorization. It records the Agent as an Agent. A descriptor, transcript or authorization statement is not an identity credential. Without a supplied fd, human mode uses the controlling terminal. `--synthetic-fixture` labels implementation fixtures; executing a test callback is not actual editorial adoption.
 
-Candidate promotion is scope-gated: only candidates with `status == accepted` and `scope_fit == true` are promoted to cards by default. Use `kdna-studio candidate override <project> <candidate-id>` only when a human intentionally overrides the scope gate.
+Only explicitly named ordinary UTF-8 `.txt`, `.md` and `.text` materials are opened. The private stdin/stdout Agent pipe carries operations, actual reply tickets and material bodies. The separate channel carries natural-language replies. The CLI supplies no model, remote service, automatic provider or global binary fallback.
 
-The Studio CLI exports complete, non-deprecated cards. Human Lock and other
-provenance records are optional review evidence, not creation permission or
-format-validity requirements.
+Follow brief → materials → distinct alternatives → actual selection → complete current preview → fresh final adoption → export. Typed `method` is optional. Its absence, undeclared own arrays and explicit empty arrays remain distinct. Component structures use the shared Core grammar. Candidate-specific criteria stay inside their respective candidates; an empty overall formation condition set is not filled from branch conditions.
 
-After export, use the runtime CLI:
+Export exclusively creates a new private directory. It writes exact Studio bytes and evidence, captures the saved asset again, calls Studio `completeSave`, writes `verification.json`, and writes version-2 `complete.json` last. Files and directory become read-only for their owner. Failure removes only the incomplete reservation made by that invocation. Library saving reports `accepted_with_live_context`, scoped to the actual process and saved-byte check. It does not prove storage durability, person identity or action authorization.
 
-```bash
-kdna validate dist/my_domain.kdna --runtime
-kdna plan-load dist/my_domain.kdna --json
-kdna load dist/my_domain.kdna --profile=compact --as=prompt
+```text
+kdna-studio verify --bundle ./new-export
+kdna-studio read --bundle ./new-export --allow-read --judgment 1
 ```
 
-`kdna-studio` is the CLI entry for Studio project authoring. `kdna` is the
-runtime control plane for inspecting, validating, packing, unpacking, and
-loading existing `.kdna` assets.
-
-## 5-minute first asset
-
-If you just installed and want to ship a KDNA asset without an LLM:
-
-```bash
-# 1. Create a project
-kdna-studio create my_domain --name @yourscope/my_domain
-
-# 2. Add at least one judgment card
-kdna-studio card add my_domain axiom \
-  --field one_sentence='specific evidence outranks broad claims' \
-  --field full_statement='Always cite the specific source that supports a judgment; broad claims without evidence are the most common cause of bad agent advice.' \
-  --field why='because vague advice fails in production' \
-  --field applies_when='["reviewing"]' \
-  --field does_not_apply_when='["formatting"]' \
-  --field failure_risk='praise without diagnosis' \
-  --field confidence='high' \
-  --field evidence_type='practice'
-
-# 3. Optional: approve and record Human Lock provenance
-kdna-studio card approve my_domain --all --by me --statement "i confirm"
-
-# 4. Export the asset
-kdna-studio export my_domain --out my_domain.kdna
-
-# 5. Verify with the runtime CLI
-kdna load my_domain.kdna --profile=compact
-```
+Static reopening keeps `creation_accepted:not_evaluated` and `live_context:unavailable`; JSON cannot restore a one-use capability. `read` requires explicit `--allow-read`, delegates request admission, scope, exact selection and byte budgets to public Read, and grants no action authority. Format1, format-absent legacy evidence and old completion sidecars are noncurrent. Preserve their original accepted releases; never relabel them to this graph.
 
-The first three AI commands (feynman, distill --ai, test, interview) work
-without `KDNA_LLM_PROVIDER` / `KDNA_LLM_API_KEY` by passing `--no-llm`. They
-return a structured but unsynthesised result. To enable real evaluation:
+The full 12-package local `file:vendor` graph and SRI lock are supplied. Before loading upstream code or materials, the CLI checks complete installed member sets, bytes, versions and one shared Core resolution, and rejects unbound optional addons. The exact archive/member declarations are in `src/public-bindings.json`.
 
-```bash
-kdna-studio llm config --provider openai --model gpt-4 --key <your-key>
-# or set KDNA_LLM_PROVIDER, KDNA_LLM_API_KEY, KDNA_LLM_MODEL
+```text
+npm ci --offline --ignore-scripts --omit=optional --no-audit --no-fund
+npm test
+npm run lint
+npm pack --offline --ignore-scripts
 ```
 
-## Runtime Export Contract
-
-`kdna-studio export` is the canonical runtime export path. It uses
-`@aikdna/kdna-studio-core` to compile the Studio project into the current KDNA
-runtime asset and then packs it with `@aikdna/kdna-core`.
-
-A KDNA runtime export contains only these top-level entries:
-
-- `mimetype`
-- `kdna.json`
-- `payload.kdnab`
-- `checksums.json`
-
-The current producer writes `format_version: 0.1.0`, payload profile
-`kdna.payload.judgment` with `profile_version: 0.1.0`, and digest profile
-`kdna.digest-basis.runtime-entry-set` with `digest_profile_version: 0.1.0`.
-These compatibility coordinates are independent of package versions.
-
-Authoring/source entries such as `KDNA_Core.json`, `KDNA_Patterns.json`, and
-`source_cards` are not runtime distribution entries. They may exist in Studio
-compile output or legacy imports, but they must not be emitted by the runtime
-export path.
-
-Being part of the official toolchain means this package is maintained by the
-KDNA project. It does not make any specific asset endorsed or suitable for
-every use case.
+An embedding that requires offline processing must independently deny network access; npm `--offline` alone is not a network boundary. No package lifecycle scripts or native optional packages are needed for this graph.
 
-## Consumption sidecars
+## Dependency coordinates and publication
 
-Studio can export route-card and consumer-index drafts for applications that
-use the consumption runtime. These files are separate from the `.kdna` export
-and are disabled by default. They are review inputs, not claims that an asset
-is automatically suitable for a task or ready for a production runtime.
+A direct declaration is either an exact SemVer or an integrity-locked `file:` coordinate. Placement follows what the documented entry needs: these `file:` coordinates belong in `dependencies`, because `npm ci --omit=dev --omit=optional` followed by `npm test` still works with the development graph omitted, whereas a `devDependencies` placement would not survive `--omit=dev`. Peers declared by vendored members are bound to this repository's own coordinates through `overrides`, so an unreadable vendor archive fails locally instead of sending npm to the registry.
 
-Use the KDNA CLI review and evaluation commands before an application enables
-a sidecar entry.
+Before publishing a release from this repository every `file:` coordinate must be replaced by the **exact registry version**, because a consumer that installs the packed artifact from a registry has no `vendor/` directory next to it. `npm run check:publish-coordinates` reports the coordinates that are still local; the publish workflow runs that gate before a package can be pushed.
 
-## Identity
-
-```bash
-kdna-studio identity init --name "Your Name"
-kdna-studio identity show
-```
-
-## Import from existing KDNA or legacy folders
-
-```bash
-# Fork an existing canonical .kdna asset (cards are imported as draft)
-kdna-studio create forked --from-kdna ./parent.kdna --name @scope/forked
-
-# Migrate a legacy JSON source folder
-kdna-studio create migrated --from-folder ./old-domain-json --name @scope/migrated
-```
+See [command contract](docs/CREATION_COMMAND_CONTRACT.md) and [Agent integration](docs/TERMINAL_AGENT_CREATION.md). Their JSONL is private transport, not a KDNA asset format. Historical project/card commands and runtime adapters stay outside the packed and default surface.
 
-Current `.kdna` imports also preserve explicitly declared `highest_question`,
-`worldview`, ordered `value_order`, and `judgment_role` values in the editable
-project. Re-export writes those values back exactly; Studio does not infer a
-replacement judgment core from an axiom.
 
-Imports preserve authored source references, `core_structure` relations,
-pattern subtypes, scenario and case metadata, extended reasoning fields, and
-source-authored evolution. Studio-only card state and lock audit records remain
-authoring provenance and are not rewritten as Runtime judgment evolution.
+## Current candidate preflight
 
-## Related
+The checked dependency graph binds Core `0.37.1-rc.browser.1`, Read
+`0.11.2-rc.browser.1` and `fast-uri` `3.1.8`. The current source ledger is
+`fixtures/runtime-candidates/current-sources.json`; `npm run verify:candidate-sources`
+rebuilds its exact Git package trees and compares every installed tar member.
+`npm run check:current-bindings` independently recomputes the complete dependency
+member receipt. These checks execute for the current candidate; historical
+registry fixtures and their retired API remain separate test material.
 
-- [KDNA Core](https://github.com/aikdna/kdna) — Official format specification
-- [kdna-cli](https://github.com/aikdna/kdna-cli) — runtime CLI for inspect, validate, pack, unpack, and load
-- [kdna-studio-core](https://github.com/aikdna/kdna-studio-core) — authoring SDK used by this CLI
-- [kdna-studio-swift](https://github.com/aikdna/kdna-studio-swift) — native Swift counterpart
+From a clean source checkpoint, `npm run candidate:generate-evidence -- --out
+<outside-repository-evidence.json> --artifact <outside-repository-package.tgz>`
+creates two byte-identical packs from exact committed blobs and validates their
+independently parsed contents. Its candidate evidence schema cannot enter the
+stable publisher. Candidate preflight does not establish registry availability,
+verified editorial identity, real human acceptance or permission to publish.
+The stable release event/tag policy and exact registry-coordinate gate remain
+required before publication.