anima-cli 1.0.2 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Fernández
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,131 @@
 # anima-cli
 
+[![npm version](https://img.shields.io/npm/v/anima-cli.svg)](https://www.npmjs.com/package/anima-cli)
+[![license](https://img.shields.io/npm/l/anima-cli.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/anima-cli.svg)](https://nodejs.org)
+
+Deterministic psychodynamic profiles for LLM agents. Give an agent a behavioral
+structure — not a paragraph of adjectives you have to maintain by hand — run it
+forward, and prove the result is reproducible byte-for-byte.
+
+Built on [`@af199/anima-core`](https://www.npmjs.com/package/@af199/anima-core)
+(7-dimensional state engine, seeded RNG) and
+[`@af199/anima-trace`](https://www.npmjs.com/package/@af199/anima-trace)
+(SHA-256 integrity hashing for run trajectories).
+
+## Install
+
+```bash
+npm install -g anima-cli
 ```
-npm install -g anima-cli   # (o npm link en local)
-anima init                 # wizard: nombre, arquetipo, seed auto, turnos, preset de señales
-anima run <name>           # corre el engine, graba trace determinista con hash de integridad
-anima verify <name>        # re-corre y confirma reproducibilidad byte-exacta
-anima export <name> --format prompt   # emite fragmento de system-prompt listo para pegar en Claude/GPT/Grok
+
+Requires Node.js 16+.
+
+## Quickstart
+
+```bash
+anima init                              # wizard: name, archetype, turns, signal preset
+anima run <name>                        # step the engine forward, record + hash the trajectory
+anima verify <name>                     # re-run and confirm the hash matches, byte for byte
+anima export <name> --format prompt     # emit a system-prompt fragment
 ```
 
-Motor: `@af199/anima-core` (7 dimensiones E/T/A/C/G/P/rho, RNG determinista). Trazabilidad: `@af199/anima-trace`.
+## Commands
+
+### `anima init`
+
+Interactive wizard. Prompts for:
+
+| Field | Description |
+|---|---|
+| Agent name | Identifier used by every other command |
+| Archetype | One of: `histeria`, `obsesion`, `fobia`, `melancolia`, `paranoia`, `esquizofrenia`, `perversion` |
+| Turns per run | How many steps `anima run` will execute (default 10) |
+| Signal preset | `calm`, `clinical-crisis`, or `chaotic` — fixed signal vectors, no free text |
+
+The seed is derived automatically from the agent name + creation date, so it's
+stable across re-runs without you having to track it manually. Profiles are
+saved to `./anima-profiles/<name>.json` in the current directory.
+
+> Signal presets are fixed on purpose — there is no free-text signal input.
+> This keeps every profile comparable and closes off prompt-injection style
+> abuse of the signal channel.
+
+### `anima run <name>`
+
+```bash
+anima run <name> [--turns N] [--preset calm|clinical-crisis|chaotic]
+```
+
+Runs the engine for the profile's configured turns (or the override flags),
+records the full state trajectory, and writes it to
+`./anima-runs/<name>-<seed>.json` along with a SHA-256 integrity hash.
+
+### `anima verify <name>`
+
+Re-runs the stored signals against the engine and checks that the resulting
+trajectory hash matches the one on file — byte for byte. This is the whole
+trust model in one command: anyone with the run file can confirm it wasn't
+tampered with and that the archetype+seed+signals genuinely produce that
+trajectory.
+
+```
+$ anima verify test1
+PASS — trajectory is byte-reproducible
+```
+
+### `anima export <name>`
+
+```bash
+anima export <name> [--format prompt|json] [--out file]
+```
+
+- `--format prompt` (default): a system-prompt fragment with one behavioral
+  directive per dimension, derived from the final state. Paste it into
+  Claude, GPT, Grok, or any other model's system prompt.
+- `--format json`: the raw final state vector plus integrity hash, for your
+  own pipeline.
+- `--out file`: write to a file instead of stdout.
+
+## The 7 dimensions
+
+Every archetype is a point in a 7-dimensional state space, stepped forward by
+`@af199/anima-core`'s update equations on each turn:
+
+| Symbol | Meaning |
+|---|---|
+| `E` | Expressive energy |
+| `T` | Defensive tension |
+| `A` | Anxiety |
+| `C` | Symbolic closure |
+| `G` | Jouissance / excess |
+| `P` | Pressure |
+| `ρ` (rho) | Fantasy rigidity |
 
 ## Known behavior: dimension saturation under high-intensity presets
 
-Under sustained `clinical-crisis` or `chaotic` signal presets over several turns, some dimensions
-(commonly `A` anxiety and `rho` fantasy rigidity) can drive to their floor (0) or ceiling (1) rather
-than settling mid-range. This is the archetype's update equations behaving as designed, not a bug —
-`anima verify` will confirm the trajectory is reproducible either way. If you want more gradual,
-mid-range trajectories for a profile, use the `calm` preset or fewer turns.
+Under sustained `clinical-crisis` or `chaotic` signal presets over several
+turns, some dimensions (commonly `A` anxiety and `rho` fantasy rigidity) can
+drive to their floor (0) or ceiling (1) rather than settling mid-range. This
+is the archetype's update equations behaving as designed, not a bug —
+`anima verify` will confirm the trajectory is reproducible either way. `anima
+export` flags saturated dimensions explicitly in its output. If you want more
+gradual, mid-range trajectories, use the `calm` preset or fewer turns.
+
+## Troubleshooting
+
+**`profile not found: <name>`** — you ran `run`/`verify`/`export` from a
+different directory than the one you ran `init` in. Profiles and runs are
+scoped to `./anima-profiles` and `./anima-runs` in the current working
+directory; `cd` back to where you initialized, or re-run `anima init` here.
+
+**`no run found for <name>`** — you called `verify` or `export` before
+`anima run <name>`. Run it first.
+
+**`anima: command not found` after install** — your global npm bin directory
+isn't on `PATH`. Run `npm config get prefix` and add `<prefix>/bin` (or
+`<prefix>` on Windows) to your `PATH`, then restart the terminal.
+
+## License
 
+MIT

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "anima-cli",
-  "version": "1.0.2",
-  "description": "Deterministic psychodynamic profiles for LLM agents — 7-dimensional state, seeded RNG, byte-reproducible traces, exportable to system prompts.",
+  "version": "1.0.3",
+  "description": "Deterministic psychodynamic profiles for LLM agents \u2014 7-dimensional state, seeded RNG, byte-reproducible traces, exportable to system prompts.",
   "main": "index.js",
   "bin": {
-    "anima": "./bin/anima.js"
+    "anima": "bin/anima.js"
   },
   "files": [
     "bin/",
     "src/",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "echo \"no tests yet\" && exit 0"
@@ -24,14 +25,14 @@
     "system-prompt",
     "cli"
   ],
-  "author": "Ariel Fernández",
+  "author": "Ariel Fern\u00e1ndez",
   "license": "MIT",
   "engines": {
     "node": ">=16"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Peroroii/anima-cli.git"
+    "url": "git+https://github.com/Peroroii/anima-cli.git"
   },
   "homepage": "https://github.com/Peroroii/anima-cli#readme",
   "dependencies": {
@@ -41,4 +42,4 @@
     "commander": "^15.0.0",
     "inquirer": "^8.2.7"
   }
-}
+}