cognetivy 0.1.4 → 0.1.6

package/README.md

@@ -1,95 +1,108 @@
-# cognetivy
+# Cognetivy
 
-**Workflow and reasoning state for AI coding assistants.** Define workflows, track runs and events, store structured artifacts — no LLMs inside, just the state layer that Cursor, Claude Code, OpenClaw (and other MCP clients) can read and write.
+![Cognetivy Studio: workflow canvas, run details, and data collected](studio_example.jpg)
 
-- **Local workspace** — one `.cognetivy/` per project; config in `~/.config/cognetivy` or `.cognetivy/config.json`.
-- **MCP server** — expose workflow, runs, artifacts, and skills to your editor/agent.
-- **Studio** — read-only browser UI for workflow, runs, and artifacts.
-- **Skills** — install and manage SKILL.md-based skills for **Cursor**, **Claude Code**, and **OpenClaw** from one place.
+Cognetivy is an open-source state layer for AI-assisted development: define workflows, track runs and events, and store structured collections in a local `.cognetivy/` workspace. No LLMs inside - just the data and tools your editor's agent uses via [Skills](https://agentskills.io/) and [MCP](https://agentskills.io/). Works with **Cursor**, **Claude Code**, **OpenClaw**, and other MCP-compatible clients.
+
+## Requirements
+
+- **Node.js** ≥ 18
+- A project directory (or an empty folder) to create a workspace in
+- A coding agent (Cursor, Claude Code, OpenClaw, etc.) working on that directory
 
 ---
 
 ## Install
 
+Run once with npx (no global install):
+
+```bash
+npx cognetivy
+```
+
+Or install globally for use from any directory and for MCP:
+
 ```bash
 npm install -g cognetivy
 ```
 
 ---
 
-## Quick start
+## Step-by-step
+
+### Step 1 - Run cognetivy
+
+Open a terminal in your project folder (or an empty folder) and run, an installer will open in the terminal:
 
 ```bash
-cognetivy init
-cognetivy studio
+npx cognetivy
 ```
 
-`init` creates `.cognetivy/` and can install skills into Cursor / Claude Code / OpenClaw. `studio` opens the read-only UI in your browser.
+---
 
-**Essential commands:**
+### Step 2 - Use the installer
 
-| Command | What it does |
-|--------|----------------|
-| `cognetivy init` | Create workspace (and optionally install skills) |
-| `cognetivy workflow get` | Show current workflow |
-| `cognetivy run start --input <json>` | Start a run |
-| `cognetivy studio` | Open Studio UI |
-| `cognetivy mcp` | Start MCP server (for Cursor / Claude Code / OpenClaw) |
+1. In the installer, choose your coding agent (Claude Code, Cursor, OpenClaw, etc.)
+2. Cognetivy will create a `.cognetivy/` workspace in the current folder.
+3. Cognetivy will install its skills into the workspace.
 
 ---
 
-## For Cursor, Claude Code, and OpenClaw
+### Step 3 - Studio opens
 
-**MCP** — So the AI can read/write workflow, runs, and artifacts:
+When the installer finishes, Cognetivy Studio opens in your browser.
 
-1. Install: `npm install -g cognetivy`
-2. Add MCP server (Cursor: **Settings → Tools & MCP → Add new**):
-   - **Command:** `cognetivy`
-   - **Args:** `mcp` (or `mcp`, `--workspace`, `/path/to/project` if needed)
-3. Restart the editor. Cognetivy tools will show up in chat.
+- You’ll see the read-only UI: workflow, runs, and collections.
 
-**Skills** — Install SKILL.md skills into each environment:
+---
 
-- **Cursor:** `cognetivy install cursor` (installs to `.cursor/skills`)
-- **Claude Code:** `cognetivy install claude`
-- **OpenClaw:** `cognetivy install openclaw`
-- **Project-only:** `cognetivy install workspace` (installs to `.cognetivy/skills`)
+### Step 4 - Ask your agent to create a workflow and run it
 
-List and manage skills: `cognetivy skills list`, `cognetivy skills info <name>`, `cognetivy skills install`, `cognetivy skills update`.
+In another chat window, ask your agent to create a workflow and run it.
 
----
+- "Create a workflow with three nodes: one that gathers requirements, one that writes a plan, and one that writes a summary. Save it as the current workflow."
+- "Start a run for the current workflow with input with the topic 'user onboarding'."
 
-## More commands
+## Connect your agent (MCP)
 
-- **Workflow:** `workflow set --file <path>`
-- **Runs:** `run status --run <id>`, `run set-name --run <id> --name "..."`
-- **Events:** `event append --run <id> [--file <path>]`
-- **Nodes:** `node start`, `node complete` (for step lifecycle)
-- **Mutations:** `mutate propose --patch <path> --reason "..."`, `mutate apply <id>`
-- **Artifacts:** `artifact-schema get/set`, `artifact list/get/set/append`
-- **Studio API only:** `cognetivy studio --api-only` (for dev with Vite)
+Cognetivy works best with **agent skills**, but you can connect via **MCP** so cognetivy tools appear in chat.
 
----
+### Cursor
 
-## Development
+1. Open **Settings** → **Tools & MCP** (or **Features** → **MCP**).
+2. Click **Add new MCP server**.
+3. Set **Name** to `cognetivy`.
+4. Set **Command** to `cognetivy` (or the full path if not on PATH).
+5. Set **Arguments** to `mcp`. If your project root is not the folder that contains `.cognetivy/`, add `--workspace` and the path to that folder (e.g. `--workspace ./example-usage`).
+6. Save and restart Cursor.
 
-```bash
-cd cli && npm install && npm run build && npm test
-```
+Cognetivy tools (workflow, run, event, collection, node, etc.) will then be available in chat.
 
-Embed Studio in the CLI build: `npm run build:full`.
+**Optional — config file:** You can instead add the server to `~/.cursor/mcp.json` (or your project’s `.cursor/mcp.json`):
 
-### Publish a new version
+```json
+{
+  "mcpServers": {
+    "cognetivy": {
+      "command": "cognetivy",
+      "args": ["mcp"]
+    }
+  }
+}
+```
 
-From the `cli` directory, with a clean working tree:
+Use `"args": ["mcp", "--workspace", "/path/to/folder/with/.cognetivy"]` if the workspace is not your current project root.
 
-```bash
-npm run release        # bump patch (0.1.3 → 0.1.4) and publish
-npm run release:minor  # bump minor (0.1.3 → 0.2.0) and publish
-npm run release:major  # bump major (0.1.3 → 1.0.0) and publish
-```
+## Commands
 
-Then push the new commit and tag: `git push && git push --tags`.
+| Command | Description |
+|--------|-------------|
+| `npx cognetivy` | Run installer and open Studio (first time) or open Studio |
+| `cognetivy workflow get` | Print current workflow |
+| `cognetivy run start --input <file>` | Start a run |
+| `cognetivy studio` | Open Studio in the browser |
+| `cognetivy mcp` | Start MCP server (for your editor) |
+| `cognetivy install cursor` | Install skills into Cursor (`claude`, `openclaw`, `workspace` also supported) |
 
 ---
 

package/dist/cli.js

@@ -51,7 +51,7 @@ async function launchStudio(workspacePath, port = STUDIO_DEFAULT_PORT) {
 }
 program
     .name("cognetivy")
-    .description("Reasoning orchestration state — workflow, runs, events, collections (no LLMs). Run with no command: init workspace if missing, then open Studio.")
+    .description("Reasoning orchestration state - workflow, runs, events, collections (no LLMs). Run with no command: init workspace if missing, then open Studio.")
     .version("0.1.0");
 program
     .command("init")
@@ -317,7 +317,7 @@ runCmd
             const nr = nodeResultByNodeId.get(node.id);
             nodesList.push({
                 node_id: node.id,
-                status: nr?.status ?? "—",
+                status: nr?.status ?? "-",
                 completed_at: nr?.completed_at,
             });
         }
@@ -443,7 +443,7 @@ collectionSchemaCmd
 });
 const collectionCmd = program
     .command("collection")
-    .description("Structured collections per run (sources, ideas — schema-backed)");
+    .description("Structured collections per run (sources, ideas - schema-backed)");
 collectionCmd
     .command("list")
     .description("List collection kinds that have data for a run")

package/dist/mcp.js

@@ -146,7 +146,7 @@ const TOOLS = [
     },
     {
         name: "collection_set",
-        description: "Replace all collections of a kind for a run. Items are validated against schema. If kind is unknown or validation fails, error includes schema—use collection_schema_add_kind first. Use **Markdown** for long text fields (summaries, theses, descriptions, reasons) so Studio renders them as rich text.",
+        description: "Replace all collections of a kind for a run. Items are validated against schema. If kind is unknown or validation fails, error includes schema-use collection_schema_add_kind first. Use **Markdown** for long text fields (summaries, theses, descriptions, reasons) so Studio renders them as rich text.",
         inputSchema: {
             type: "object",
             properties: {
@@ -391,7 +391,7 @@ async function handleToolsCall(name, args, cwd) {
                         const nr = nodeResultByNodeId.get(node.id);
                         nodesList.push({
                             node_id: node.id,
-                            status: nr?.status ?? "—",
+                            status: nr?.status ?? "-",
                             completed_at: nr?.completed_at,
                         });
                     }

package/dist/skills.js

@@ -335,11 +335,11 @@ Workflows, runs, node results, and schema-backed collections. Run commands from
    \`\`\`
    Capture \`run_id\` (first line) or \`COGNETIVY_RUN_ID=...\` (second line).
 
-2. **Inspect workflow**: \`cognetivy workflow get\` — note \`nodes[].id\`, \`input_collections\`, \`output_collections\`.
+2. **Inspect workflow**: \`cognetivy workflow get\` - note \`nodes[].id\`, \`input_collections\`, \`output_collections\`.
 
 3. **Schema**: \`cognetivy collection-schema get\`. Add missing kinds with \`collection-schema set\` so output collections exist.
 
-4. **For each node:** Do the work, then **one call** — \`node complete\`:
+4. **For each node:** Do the work, then **one call** - \`node complete\`:
    \`\`\`bash
    cognetivy node complete --run <run_id> --node <node_id> --status completed [--output "text" | --output-file path] [--collection-kind <kind>]
    \`\`\`
@@ -357,11 +357,11 @@ Workflows, runs, node results, and schema-backed collections. Run commands from
 
 ## Runs
 
-\`run start\` (prints \`run_id\`, seeds \`run_input\`), \`run status --run <id> [--json]\` (nodes + collection counts — use to verify), \`run complete\`, \`run set-name\`.
+\`run start\` (prints \`run_id\`, seeds \`run_input\`), \`run status --run <id> [--json]\` (nodes + collection counts - use to verify), \`run complete\`, \`run set-name\`.
 
 ## Events
 
-\`event append --run <run_id> [--file <path>]\` — omit \`--file\` to read from stdin. Event JSON: \`type\`, \`data\` (for step events set \`data.step\` = node id). E.g. \`echo '{"type":"step_completed","data":{"step":"synthesize"}}' | cognetivy event append --run <run_id>\`.
+\`event append --run <run_id> [--file <path>]\` - omit \`--file\` to read from stdin. Event JSON: \`type\`, \`data\` (for step events set \`data.step\` = node id). E.g. \`echo '{"type":"step_completed","data":{"step":"synthesize"}}' | cognetivy event append --run <run_id>\`.
 
 ## Node results
 
@@ -374,7 +374,7 @@ Usually covered by \`node complete\`. For inspect or when not using it: \`node-r
 \`collection-schema get\` / \`set --file\` (kinds + \`item_schema\`). \`collection list --run <id>\`, \`collection get --run <id> --kind <kind>\`. \`collection set\` / \`collection append\` need \`--node\` and \`--node-result\` (or use \`node complete --collection-kind\` which creates the result). Omit \`--file\` to read from stdin.
 - **Many items:** Prefer incremental \`collection append\` or \`node complete\` per item instead of one large \`collection set\`. Use Markdown in long text fields for Studio.
 
-**Payload:** Must match \`item_schema\` for the kind; do not include \`created_at\`, \`created_by_node_id\` — cognetivy adds them.
+**Payload:** Must match \`item_schema\` for the kind; do not include \`created_at\`, \`created_by_node_id\` - cognetivy adds them.
 
 ---
 
@@ -392,7 +392,7 @@ Usually covered by \`node complete\`. For inspect or when not using it: \`node-r
 ## Performance
 
 - **Smaller context:** Per-item extraction (e.g. per-video) over all-at-once when a node maps over a list.
-- **Parallel sub-agents:** For data-parallel nodes (e.g. 10 transcripts), spawning one agent per item in parallel can yield ~10x wall-clock speedup — highest-leverage for map-over-list workflows.
+- **Parallel sub-agents:** For data-parallel nodes (e.g. 10 transcripts), spawning one agent per item in parallel can yield ~10x wall-clock speedup - highest-leverage for map-over-list workflows.
 - **Structured output:** Future extensions may enforce "output must match this schema" so the agent skips manual schema-checking.
 `;
 }
@@ -403,42 +403,42 @@ function getCognetivyReferenceContent() {
 Full command reference. Use from project root (directory containing \`.cognetivy/\`).
 
 ## workflow
-- \`cognetivy workflow list\` — list workflows.
-- \`cognetivy workflow create --name <string> [--id <string>] [--description <string>]\` — create a workflow (creates v1 and default schema).
-- \`cognetivy workflow select --workflow <workflow_id>\` — select current workflow.
-- \`cognetivy workflow versions [--workflow <workflow_id>]\` — list versions for a workflow.
-- \`cognetivy workflow get [--workflow <workflow_id>] [--version <version_id>]\` — print a workflow version JSON.
-- \`cognetivy workflow set --file <path> [--workflow <workflow_id>] [--name <string>]\` — set workflow version from JSON file (creates new version and sets it current).
+- \`cognetivy workflow list\` - list workflows.
+- \`cognetivy workflow create --name <string> [--id <string>] [--description <string>]\` - create a workflow (creates v1 and default schema).
+- \`cognetivy workflow select --workflow <workflow_id>\` - select current workflow.
+- \`cognetivy workflow versions [--workflow <workflow_id>]\` - list versions for a workflow.
+- \`cognetivy workflow get [--workflow <workflow_id>] [--version <version_id>]\` - print a workflow version JSON.
+- \`cognetivy workflow set --file <path> [--workflow <workflow_id>] [--name <string>]\` - set workflow version from JSON file (creates new version and sets it current).
 
 ## run
-- \`cognetivy run start --input <path> [--name <string>] ...\` — start run; prints run_id (seeds run_input + __system__).
-- \`cognetivy run status --run <run_id> [--json]\` — node completion + collection item counts.
+- \`cognetivy run start --input <path> [--name <string>] ...\` - start run; prints run_id (seeds run_input + __system__).
+- \`cognetivy run status --run <run_id> [--json]\` - node completion + collection item counts.
 - \`cognetivy run complete --run <run_id>\`, \`run set-name --run <run_id> --name <string>\`.
 
 ## node
-- \`cognetivy node start --run <run_id> --node <node_id>\` — step_started + started node result; prints COGNETIVY_NODE_RESULT_ID.
-- \`cognetivy node complete --run <run_id> --node <node_id> --status completed [--output ...] [--collection-kind <kind>]\` — node result + optional collection (omit --collection-file to read from stdin) + step_completed.
+- \`cognetivy node start --run <run_id> --node <node_id>\` - step_started + started node result; prints COGNETIVY_NODE_RESULT_ID.
+- \`cognetivy node complete --run <run_id> --node <node_id> --status completed [--output ...] [--collection-kind <kind>]\` - node result + optional collection (omit --collection-file to read from stdin) + step_completed.
 
 ## event
-- \`cognetivy event append --run <run_id> [--file <path>] [--by <string>]\` — append event (omit --file to read from stdin). Step events: data.step = node id.
+- \`cognetivy event append --run <run_id> [--file <path>] [--by <string>]\` - append event (omit --file to read from stdin). Step events: data.step = node id.
 
 ## collection-schema
-- \`cognetivy collection-schema get [--workflow <workflow_id>]\` — print workflow-scoped schema (kinds, item_schema, references).
-- \`cognetivy collection-schema set --file <path> [--workflow <workflow_id>]\` — set schema from JSON.
+- \`cognetivy collection-schema get [--workflow <workflow_id>]\` - print workflow-scoped schema (kinds, item_schema, references).
+- \`cognetivy collection-schema set --file <path> [--workflow <workflow_id>]\` - set schema from JSON.
 
 ## collection
-- \`cognetivy collection list --run <run_id>\` — list kinds that have data for run.
-- \`cognetivy collection get --run <run_id> --kind <kind>\` — get all items of kind.
-- \`cognetivy collection set --run <run_id> --kind <kind> [--file <path>] --node <node_id> --node-result <node_result_id>\` — replace items (omit --file for stdin).
-- \`cognetivy collection append --run <run_id> --kind <kind> [--file <path>] --node <node_id> --node-result <node_result_id> [--id <id>]\` — append one item (omit --file for stdin).
+- \`cognetivy collection list --run <run_id>\` - list kinds that have data for run.
+- \`cognetivy collection get --run <run_id> --kind <kind>\` - get all items of kind.
+- \`cognetivy collection set --run <run_id> --kind <kind> [--file <path>] --node <node_id> --node-result <node_result_id>\` - replace items (omit --file for stdin).
+- \`cognetivy collection append --run <run_id> --kind <kind> [--file <path>] --node <node_id> --node-result <node_result_id> [--id <id>]\` - append one item (omit --file for stdin).
 
 ## node-result
-- \`cognetivy node-result list --run <run_id>\` — list node results for run.
-- \`cognetivy node-result get --run <run_id> --node <node_id>\` — get node result.
-- \`cognetivy node-result set --run <run_id> --node <node_id> --status <started|completed|failed|needs_human> [--id <node_result_id>] [--output-file <path> | --output <string>]\` — set node result.
+- \`cognetivy node-result list --run <run_id>\` - list node results for run.
+- \`cognetivy node-result get --run <run_id> --node <node_id>\` - get node result.
+- \`cognetivy node-result set --run <run_id> --node <node_id> --status <started|completed|failed|needs_human> [--id <node_result_id>] [--output-file <path> | --output <string>]\` - set node result.
 
 ## studio
-- \`cognetivy studio [--workspace <path>] [--port <port>]\` — open read-only Studio (workflow, runs, events, collections) in browser.
+- \`cognetivy studio [--workspace <path>] [--port <port>]\` - open read-only Studio (workflow, runs, events, collections) in browser.
 `;
 }
 const REFERENCE_FILENAME = "REFERENCE.md";

package/dist/studio-server.js

@@ -98,7 +98,7 @@ async function handleApi(cwd, method, pathname, res, body, searchParams) {
     }
     const apiMatch = pathname.replace(/^\/api\/?/, "").split("/").filter(Boolean);
     try {
-        // PATCH /api/runs/:id — update run name
+        // PATCH /api/runs/:id - update run name
         if (method === "PATCH" && apiMatch[0] === "runs" && apiMatch.length === 2) {
             const runId = apiMatch[1];
             if (!(await runExists(runId, cwd))) {

package/dist/workspace.js

@@ -14,7 +14,7 @@ export const EVENTS_DIR = "events";
 export const COLLECTIONS_DIR = "collections";
 export const NODE_RESULTS_DIR = "node-results";
 const GITIGNORE_SNIPPET = `
-# cognetivy — ignore runtime data; commit workflows/*/versions/
+# cognetivy - ignore runtime data; commit workflows/*/versions/
 .cognetivy/runs/
 .cognetivy/events/
 .cognetivy/collections/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognetivy",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Reasoning orchestration state: workflow structure, run logs, and versioned mutations",
   "type": "module",
   "main": "dist/index.js",
@@ -46,6 +46,7 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "studio_example.jpg"
   ]
 }