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

package/README.md

@@ -1,294 +1,64 @@
-# @aikdna/kdna-studio-cli
+# KDNA Studio CLI — typed current creation
 
-> **Status:** Pre-release authoring toolchain. This repository contains the
-> unreleased `0.11.0` corrective candidate; the published incumbent remains
-> `0.10.2`. Candidate behavior must not be described as already published.
+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.
 
-Official terminal entry for KDNA judgment asset creation. The default Creation
-Engine guides a user or terminal Agent from purpose and source material through
-judgment review, boundary examples, confirmation, repair, a managed test
-candidate, and final exact-byte delivery. It does not require the Studio app
-or manual `.kdna` format editing.
+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:
 
-Two creation paths remain useful: interview-first (articulate judgment
-directly) and material-first (provide content, find the patterns, review what
-belongs in scope).
-
-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. Any future multi-asset use requires an explicit, separately admitted Host contract; it is not an implicit Studio export behavior.
-
-This package provides the `kdna-studio` command. Its default Agent surface
-speaks in purpose, material, judgment, boundary, example, confirmation, and
-export terms. The existing project, evidence, candidate, and card commands
-remain available as an expert authoring surface.
-
-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@0.10.2
-```
-
-That command installs the published incumbent. To assess the unreleased
-`0.11.0` candidate, use this source repository and its exact candidate
-dependency coordinates; do not mix candidate documentation with npm `latest`.
-
-## Usage
-
-For a terminal Agent, start with the user's ordinary-language goal and an
-optional explicit material path. The Host translates that request into private
-machine input and generates stable technical coordinates. A normal user never
-supplies a mode enum, Agent ID, operation ID, digest, schema, signing key,
-receipt, seed, or benchmark coordinate.
-
-```bash
-# Stable public machine templates; do not inspect package source for shapes.
-kdna-studio guide-agent --action create --json
-# For every command below, the Host streams its private JSON/text request to
-# stdin from memory. Private purpose, answers and judgments are not ordinary
-# project files and never go in argv.
-kdna-studio create-agent my_creation --input-stdin
-kdna-studio inventory-agent my_creation --material ./notes.md \
-  --input-stdin --json
-# After exact inventory/policy approval, deliver only the accepted source.
-private_material_file="$(mktemp)"
-chmod 600 "$private_material_file"
-trap 'rm -f "$private_material_file"' EXIT INT TERM
-kdna-studio deliver-material my_creation \
-  --input-stdin \
-  --private-output-file "$private_material_file" --json
-kdna-studio guide-agent my_creation --json
-kdna-studio resume my_creation --json
-kdna-studio status my_creation --json
-kdna-studio answer my_creation --input-stdin
-kdna-studio review my_creation --input-stdin
-kdna-studio try my_creation --input-stdin
-kdna-studio repair my_creation --input-stdin
-kdna-studio export-agent my_creation --json
-# Only after all three gates bind the same exact managed candidate:
-kdna-studio finalize-agent my_creation --out dist/my_creation.kdna --json
+```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
 ```
 
-For an approved named remote processor, the Host reads the mode-0600 temporary
-file into that named model context and deletes it in `finally`. A dedicated
-adapter may use fd 3 instead. This is Host-declared remote processing under the
-named provider retention boundary; it is not verified-local or a claim that
-model input is log-free. The generic CLI fails closed when separately attested
-local processing is required.
-
-The machine API uses a Host-generated, caller-stable operation coordinate.
-Exact retry is inert while its semantic coordinate remains current; stale
-semantic replay and changed input, material bytes, output path, or protection
-mode fail closed. This is a Host automation contract, not a user prompt.
+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.
 
-`status` reports the next unresolved decision plus the separate
-`JUDGMENT_ACCEPTED`, `FORMAT_VALID`, and `APPLICATION_VERIFIED` gates.
-`compile_ready` is only readiness to build a managed candidate. `export-agent`
-can establish the exact-byte format gate but never writes an incomplete
-candidate to the user's final path. Later official Host orchestration freezes
-the `application-adoption-fidelity` plan, loads the exact managed bytes in a
-fresh Consumer context, and obtains independent evaluation and scenario-local
-stability evidence. The ordinary user does not assemble role keys, signatures,
-plans, or receipts.
+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 machine-readable envelope exposes private Creation vocabulary and recovery
-coordinates needed for another Agent to resume. It is not ordinary log
-content. It does not return source bodies, absolute source paths, passwords,
-decrypted payloads, or private keys. See
-[Terminal Agent Creation](docs/TERMINAL_AGENT_CREATION.md) and the
-[command contract](docs/CREATION_COMMAND_CONTRACT.md).
+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.
 
-The expert authoring surface remains available:
+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-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
+```text
+kdna-studio verify --bundle ./new-export
+kdna-studio read --bundle ./new-export --allow-read --judgment 1
 ```
 
-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.
-
-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.
+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.
 
-After export, use the runtime CLI:
+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 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
+npm ci --offline --ignore-scripts --omit=optional --no-audit --no-fund
+npm test
+npm run lint
+npm pack --offline --ignore-scripts
 ```
 
-`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.
-
-## First small asset
-
-Tell a compatible terminal Agent:
+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.
 
-> Create a KDNA that keeps new titles to eight words or fewer. Use
-> `./title-notes.md`. This current remote terminal Host may process that exact
-> file under its named provider retention policy.
-> Save the result as an ordinary local file, but do not publish or share it.
+## Dependency coordinates and publication
 
-The Agent chooses the private machine fields, previews material without
-reading it, binds the exact preview when it matches the user's stated
-authorization, and shows the next meaningful semantic decision. It asks again
-only for an unexpected scope, sensitive item, coverage gap, destination
-change, or genuine ambiguity. One material file, one complete Judgment Unit,
-no relation, and no correction can be sufficient. Zero-material
-interview-first work, small collections, and paged large collections use the
-same state machine; file count is not an acceptance score.
+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.
 
-Verified local-only processing is available only through a separately trusted
-local Host adapter. A remote terminal Host must fail before reading when the
-user requires verified-local handling; fd 3 or a caller-supplied digest cannot
-upgrade remote processing into a locality proof.
-
-A review can confirm `reviewed-no-change`. Highest question, worldview, value
-order, priority, exception, conflict, and other complex structures appear only
-when the actual asset needs them.
-
-An explicitly approved material source can also be a current packaged `.kdna`.
-It is validated,
-authorized-loaded, Studio-reimported, and converted into reviewable derivation
-candidates without copying its raw payload into the workspace. Protected
-source assets use `--password-stdin`. Directory shape alone does not declare
-material historical, current, migrated, owned, or authoritative; every source
-starts with an honest unknown/review state.
-
-The expert `distill --ai` and `interview` commands can use a configured model
-provider:
-
-```bash
-printf '%s\n' "$KDNA_LLM_API_KEY" | \
-  kdna-studio llm config --provider openai --model gpt-4 --key-pipe
-# Provider/model/key environment variables can also configure a one-shot run.
-```
+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.
 
-External AI providers must use a canonical HTTPS base URL. Plain HTTP is
-accepted only for local development at the exact numeric loopback hosts
-`127.0.0.1` or `[::1]`; `localhost`, LAN addresses, URL credentials, query
-strings, and fragments are rejected. Provider redirects are not followed with
-API keys or authoring material, and provider response bodies are not copied
-into CLI errors.
-
-The Creation Engine `try` command records semantic examples and their reviewed
-results; it is separate from the retired Test Lab UI. Test Lab and Feynman
-workshop implementations remain in the source repository
-for research and regression coverage. Published releases up to and including
-0.10.2 shipped them as CLI commands in the npm tarball; the current
-development line removes them from the default CLI and from the npm release
-tarball, effective with the next release after 0.10.2. The public CLI
-contract remains the create, review, compile, and export path shown above.
-
-## Runtime Export Contract
-
-`kdna-studio export-agent` creates the managed candidate and may establish its
-exact-byte `FORMAT_VALID` result. It is not Creation Accepted or
-`CREATION_COMPLETE`; final delivery remains blocked until all three gates bind
-that same candidate.
-`kdna-studio export` remains the expert Studio-project export path. Both use
-`@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.
-
-## Consumption sidecars
-
-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.
-
-Use the KDNA CLI review and evaluation commands before an application enables
-a sidecar entry.
-
-## Identity
-
-```bash
-kdna-studio identity init --name "Your Name"
-kdna-studio identity show
-```
-
-A configured machine-local identity is not inherited by `create` or `migrate`.
-Use `--use-local-identity` only when that identity is intentionally the creator
-for the current work. Signing and identity-management commands continue to
-load identity explicitly.
-
-## 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.