@tuned-tensor/cli 0.16.0 → 0.18.0

package/README.md

@@ -21,6 +21,11 @@ Inference choice is independent of where training uses a GPU. Your AWS GPU
 needs AWS credentials and SSH access; TT account operations under `tt cloud`
 require a TT access token.
 
+New to cloud GPU training? Follow [your first AWS run](docs/local-runtime/aws-gpu.md)
+for project creation, AWS quota and SSH setup, a preview, training, result
+verification, and shutdown. You still run `tt pipeline run` on your laptop;
+`tt cloud` is for TT account records, not user-owned GPU execution.
+
 ## Unified commands
 
 Local workflows remain the default: `tt pipeline run`, `tt runs list`,
@@ -86,6 +91,14 @@ npm run build
 npm link
 ```
 
+## Behavior spec workflow
+
+`tunedtensor.json` is the source of truth for behavior and training settings.
+Use `/spec`, `/spec diff`, `/spec validate`, and `/spec history` in the shell to
+review it without a model call. Ask the agent for changes, inspect its proposed
+diff, then `/approve` to save a validated edit with revision history. Pipeline
+runs use the saved spec. See [the spec workflow](docs/spec-workflow.md).
+
 ## Conversational terminal
 
 The interactive agent harness and conversation state run on your laptop.
@@ -157,11 +170,11 @@ Ask TT anything. Known commands run directly.
 ```
 
 Ordinary sentences go through the locally orchestrated model session. The
-model has no shell or general filesystem tool. It can prepare one new folder
-directly beneath the shell's current working directory with a validated
+model has no shell or general filesystem tool. It can read and propose reviewed
+edits to an existing spec, or prepare one new folder directly beneath the shell's current working directory with a validated
 `tunedtensor.json`, or prepare a local pipeline dry-run sealed to the reviewed
-workspace and spec contents. Neither action starts until `/approve`. The tools refuse path
-traversal, symlinked workspace roots, existing spec targets, unsupported spec
+workspace and spec contents. Writes and pipeline previews wait for `/approve`. The tools refuse path
+traversal, symlinked workspace roots, overwriting a new-project target, unsupported spec
 fields, cloud pipeline targets, and spec changes after review. Known CLI
 commands such as `runs list`, `doctor`, and `models list` still execute directly.
 Prefix a command with `:` when you want to make that intent explicit.
@@ -275,25 +288,32 @@ expected output for every example. Treat those metrics as an end-to-end
 execution and overfit check—not held-out capability or multi-GPU evidence when
 no validation corpus is configured.
 
+`tunedtensor.json` contains behavior, training settings, optional `evaluation`,
+`runtime`, and advanced `pipeline` sections. Pipelines use the embedded recipe
+or derive it from the saved spec. Only explicit `--file` loads a separate recipe;
+it cannot override a conflicting embedded recipe. Foundation recipes must match
+the spec's training settings.
+
 ```bash
-tt pipeline init --file pipeline.json
-tt pipeline init --engine foundation --file foundation.pipeline.json
-tt pipeline validate --file pipeline.json
-tt --json pipeline plan --file pipeline.json
-tt --json pipeline run --dry-run --file pipeline.json --only baseline
-tt --json pipeline run --file pipeline.json \
-  --spec tunedtensor.json --config local-runner.json
-tt init --engine foundation --name "Tiny GPT"
-tt --json pipeline run --spec tunedtensor.json --dry-run
-tt pipeline run --spec tunedtensor.json --resume /absolute/path/to/foundation-run
+tt pipeline validate --spec tunedtensor.json
+tt --json pipeline plan --spec tunedtensor.json
+tt pipeline run --spec tunedtensor.json --dry-run
+tt pipeline run --spec tunedtensor.json
+# Optional: embed the current derived recipe for customization
+tt pipeline init --spec tunedtensor.json
+# Existing projects: consolidate sidecars, retaining .bak copies
+tt pipeline migrate --spec tunedtensor.json
 ```
 
-When `--config` is omitted, `pipeline run` uses `local-runner.json` beside the
-selected spec when that file exists.
+Relative runtime paths resolve beside the spec. New project state uses
+`.tuned-tensor/store` and `.tuned-tensor/artifacts`. Legacy `local-runner.json`
+remains readable with a warning; migrate it before adding inline runtime or
+evaluation settings. See [single-file examples](examples/single-spec) and the
+[spec workflow](docs/spec-workflow.md).
 
 `--only` and `--skip` preserve dependency safety: a selected step cannot refer
-to an omitted predecessor. Keep step targets local and configure `gpu` in
-`local-runner.json` to execute GPU work on your AWS instance. Adapter and
+to an omitted predecessor. Keep step targets local and configure `runtime.gpu` in
+`tunedtensor.json` to execute GPU work on your AWS instance. Adapter and
 foundation workflows use the same local pipeline. The TT agent may describe,
 validate, and prepare a sealed pipeline action; only deterministic `/approve`
 handling can execute it.
@@ -370,20 +390,22 @@ tt init \
   --model Qwen/Qwen3.5-2B
 ```
 
-Edit the generated `tunedtensor.json`, replacing both placeholder examples.
+Edit the generated `tunedtensor.json`, replacing the placeholder system prompt and both placeholder examples.
 For a local GPU, `tt hardware` reports this machine's training and serving
-capacity. For an AWS GPU, save the following as `local-runner.json` beside the
-spec, replacing the instance, region, profile and SSH settings with your own:
+capacity. For an AWS GPU, add the following `runtime` section to your
+`tunedtensor.json`, replacing the instance, region, profile and SSH settings with your own:
 
 ```json
 {
-  "gpu": {
-    "provider": "aws",
-    "profile": "research",
-    "region": "eu-west-1",
-    "instanceId": "i-0123456789abcdef0",
-    "user": "ubuntu",
-    "identityFile": "~/.ssh/research-gpu.pem"
+  "runtime": {
+    "gpu": {
+      "provider": "aws",
+      "profile": "research",
+      "region": "eu-west-1",
+      "instanceId": "i-0123456789abcdef0",
+      "user": "ubuntu",
+      "identityFile": "~/.ssh/research-gpu.pem"
+    }
   }
 }
 ```
@@ -402,7 +424,7 @@ tt pipeline run --spec tunedtensor.json --dry-run
 tt pipeline run --spec tunedtensor.json
 ```
 
-These commands discover the adjacent `local-runner.json`. The preview needs
+These commands read runtime and evaluation settings from the core spec. The preview needs
 no GPU or AWS connection. Results return to the local run and model stores:
 
 ```bash
@@ -434,7 +456,7 @@ Activation is optional and requires the run to pass a configured
 `generalRegression` gate. Without that suite, `tt models activate` fails
 closed. `tt serve active` also fails closed if nothing is activated — it does
 not silently serve the protected base model. Once activated, use
-`tt serve active --config local-runner.json`.
+`tt serve active`.
 
 `tt serve base` does not automatically inject the adjacent project spec.
 Pass `--spec tunedtensor.json` when the server should enforce its instructions.