coherence-cli 0.6.2 → 0.7.1

package/README.md

@@ -159,6 +159,35 @@ Every part of the network links to every other. Jump in wherever makes sense for
 
 ---
 
+## API key — what it's for and how to get one
+
+**No key needed for:** Browsing ideas, searching specs, viewing lineage, checking ledgers, reading node status, exploring the network.
+
+**Key needed for:** Updating idea status, recording contributions, linking identities, voting on governance, creating specs, managing federation.
+
+Most people start without a key. You only need one when you're ready to contribute.
+
+### Get a key (interactive)
+
+```bash
+cc setup
+```
+
+This walks you through choosing a name, linking an identity (GitHub, Discord, Ethereum, etc.), and generates a key tied to your identity. Stored in `~/.coherence-network/config.json`.
+
+### Manual setup
+
+```bash
+export COHERENCE_API_KEY=your-key
+```
+
+Or set it permanently:
+
+```bash
+cc identity set myname
+# Key is auto-generated and stored in ~/.coherence-network/config.json
+```
+
 ## Configuration
 
 By default, `cc` talks to the public API at `https://api.coherencycoin.com`. Override with environment variables:
@@ -167,7 +196,7 @@ By default, `cc` talks to the public API at `https://api.coherencycoin.com`. Ove
 # Point to a local node
 export COHERENCE_API_URL=http://localhost:8000
 
-# Enable write operations
+# Set API key for write operations
 export COHERENCE_API_KEY=your-key
 ```
 
@@ -175,6 +204,82 @@ Config is stored in `~/.coherence-network/config.json`.
 
 ---
 
+## Search, filter, and CRUD
+
+Every resource in the network is accessible from the CLI. Here's how to find what you need:
+
+### Ideas — the core unit
+
+```bash
+cc ideas                      # Top 20 by free-energy score (ROI × confidence)
+cc ideas 50                   # Top 50
+cc idea <id>                  # Full detail: scores, open questions, children, tasks
+cc idea create <id> <name>    # Create a new idea
+  --desc "..."                #   Description
+  --value 50 --cost 5         #   Potential value and estimated cost
+  --parent <parent-id>        #   Parent idea (fractal hierarchy)
+```
+
+### Specs — blueprints linked to ideas
+
+```bash
+cc specs                      # List specs with ROI and value gap
+cc specs 50                   # More results
+cc spec <id>                  # Full spec: summary, pseudocode, implementation status
+```
+
+### Tasks — the work queue
+
+```bash
+cc tasks                      # All pending tasks
+cc tasks running              # In-progress tasks
+cc tasks completed 20         # Last 20 completed
+cc task <id>                  # Full task: direction, idea link, output, provider
+cc task next                  # Claim the highest-priority task
+cc task seed <idea-id> spec   # Create a task for an idea
+```
+
+### Contributors and identity
+
+```bash
+cc identity                   # Your linked accounts and CC balance
+cc identity lookup github <handle>  # Find any contributor by provider identity
+```
+
+### Nodes and federation
+
+```bash
+cc nodes                      # All nodes: status, SHA, providers, last seen
+cc inbox                      # Messages from other nodes
+cc msg <node> <text>          # Send a message
+cc cmd <node> status          # Remote diagnostics
+```
+
+### Searching and filtering
+
+Most list commands accept a limit. For deeper filtering, use the API directly:
+
+```bash
+# Search ideas by keyword
+curl -s "$CN_API/api/ideas/cards?search=treasury&limit=10" | jq '.items[] | {id, name}'
+
+# Search specs by keyword
+curl -s "$CN_API/api/spec-registry/cards?search=auth&limit=10" | jq '.items[] | {spec_id, title}'
+
+# Filter tasks by type and status
+curl -s "$CN_API/api/agent/tasks?status=completed&task_type=review&limit=10" | jq '.tasks[] | {id, task_type}'
+
+# Contributor ledger
+curl -s "$CN_API/api/contributions/ledger/seeker71" | jq '.balance'
+
+# Ideas by parent (fractal drill-down)
+curl -s "$CN_API/api/ideas/<parent-id>" | jq '.child_idea_ids'
+```
+
+The full API has 215 endpoints across 20 resource groups — see [api.coherencycoin.com/docs](https://api.coherencycoin.com/docs) for the complete reference. The CLI covers the most common operations; the API covers everything.
+
+---
+
 ## All commands
 
 ```

package/bin/cc.mjs

@@ -15,6 +15,7 @@ import { showStatus, showResonance } from "../lib/commands/status.mjs";
 import { showIdentity, linkIdentity, unlinkIdentity, lookupIdentity, setupIdentity, setIdentity } from "../lib/commands/identity.mjs";
 import { listNodes, sendMessage, readMessages, sendCommand } from "../lib/commands/nodes.mjs";
 import { listTasks, showTask, claimTask, claimNext, reportTask, seedTask } from "../lib/commands/tasks.mjs";
+import { setup } from "../lib/commands/setup.mjs";
 
 // Version check — non-blocking, runs in background
 const require = createRequire(import.meta.url);
@@ -69,6 +70,7 @@ const COMMANDS = {
   inbox:      () => readMessages(args),
   tasks:      () => listTasks(args),
   task:       () => handleTask(args),
+  setup:      () => setup(args),
   update:     () => selfUpdate(),
   version:    () => console.log(`cc v${LOCAL_VERSION}`),
   help:       () => showHelp(),

package/lib/commands/nodes.mjs

@@ -119,7 +119,16 @@ export async function listNodes() {
 
     const ago = ageMin < 1 ? "now" : ageMin < 60 ? `${ageMin}m ago` : `${Math.floor(ageMin / 60)}h ago`;
 
-    console.log(`  ${dot} ${icon}  \x1b[1m${node.hostname || "?"}\x1b[0m  ${ago}`);
+    // Git version from capabilities
+    const git = node.capabilities?.git || {};
+    const sha = git.local_sha || "?";
+    const originSha = git.origin_sha || "?";
+    const upToDate = git.up_to_date === "yes";
+    const versionTag = upToDate
+      ? `\x1b[32m${sha}\x1b[0m`
+      : `\x1b[31m${sha} (origin: ${originSha})\x1b[0m`;
+
+    console.log(`  ${dot} ${icon}  \x1b[1m${node.hostname || "?"}\x1b[0m  ${ago}  sha:${versionTag}`);
     console.log(`     ${providers.join(", ")}`);
     console.log(`     id: ${node.node_id}`);
     console.log();

package/lib/commands/setup.mjs

@@ -0,0 +1,133 @@
+/**
+ * Interactive onboarding: cc setup
+ *
+ * Guides a new contributor through identity + API key setup.
+ * Non-interactive mode: cc setup --name <name> --provider <p> --id <id>
+ */
+
+import { get, post } from "../api.mjs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+
+const CONFIG_DIR = join(homedir(), ".coherence-network");
+const KEYS_FILE = join(CONFIG_DIR, "keys.json");
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function loadKeys() {
+  try {
+    return JSON.parse(readFileSync(KEYS_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveKeys(keys) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(KEYS_FILE, JSON.stringify(keys, null, 2), { mode: 0o600 });
+}
+
+export async function setup(args) {
+  // Check if already set up
+  const keys = loadKeys();
+  if (keys.api_key && keys.contributor_id) {
+    console.log(`\n\x1b[32m✓\x1b[0m Already set up as \x1b[1m${keys.contributor_id}\x1b[0m`);
+    console.log(`  API key: ${keys.api_key.slice(0, 12)}...`);
+    console.log(`  Provider: ${keys.provider}:${keys.provider_id}`);
+    console.log(`\n  To reconfigure: rm ${KEYS_FILE} && cc setup`);
+    return;
+  }
+
+  // Non-interactive mode
+  const nameIdx = args.indexOf("--name");
+  const providerIdx = args.indexOf("--provider");
+  const idIdx = args.indexOf("--id");
+
+  if (nameIdx >= 0 && providerIdx >= 0 && idIdx >= 0) {
+    const name = args[nameIdx + 1];
+    const provider = args[providerIdx + 1];
+    const providerId = args[idIdx + 1];
+    return await completeSetup(name, provider, providerId);
+  }
+
+  // Interactive mode
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log(`
+\x1b[1mCoherence Network — Contributor Setup\x1b[0m
+
+This will create your contributor identity and generate a personal API key.
+Everything you create, contribute, and invest will be attributed to you.
+`);
+
+  const name = await ask(rl, "  Your name (will be your contributor ID): ");
+  if (!name.trim()) {
+    console.log("\x1b[31m✗\x1b[0m Name is required");
+    rl.close();
+    return;
+  }
+
+  console.log(`
+  Link an identity so others can find and verify you.
+  Providers: github, email, ethereum, discord, x, linkedin, telegram, ...
+`);
+
+  const provider = await ask(rl, "  Provider (e.g. github): ");
+  const providerId = await ask(rl, `  Your ${provider || "provider"} handle/address: `);
+
+  rl.close();
+
+  if (!provider.trim() || !providerId.trim()) {
+    console.log("\x1b[31m✗\x1b[0m Provider and handle are required");
+    return;
+  }
+
+  await completeSetup(name.trim(), provider.trim().toLowerCase(), providerId.trim());
+}
+
+async function completeSetup(name, provider, providerId) {
+  console.log(`\n  Setting up \x1b[1m${name}\x1b[0m with ${provider}:${providerId}...`);
+
+  // Generate API key
+  const result = await post("/api/auth/keys", {
+    contributor_id: name,
+    provider,
+    provider_id: providerId,
+  });
+
+  if (!result || !result.api_key) {
+    console.log(`\x1b[31m✗\x1b[0m Setup failed: ${JSON.stringify(result)}`);
+    return;
+  }
+
+  // Save to config
+  const keys = {
+    contributor_id: name,
+    api_key: result.api_key,
+    provider,
+    provider_id: providerId,
+    created_at: result.created_at,
+    scopes: result.scopes,
+  };
+  saveKeys(keys);
+
+  console.log(`
+\x1b[32m✓\x1b[0m Setup complete!
+
+  Contributor: \x1b[1m${name}\x1b[0m
+  Identity:    ${provider}:${providerId}
+  API key:     ${result.api_key.slice(0, 20)}...
+  Saved to:    ${KEYS_FILE}
+
+  You can now:
+    cc ideas              Browse ideas
+    cc share              Submit a new idea
+    cc contribute         Record a contribution
+    cc stake <id> <cc>    Invest in an idea
+    cc status             Check network health
+`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coherence-cli",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Coherence Network CLI \u2014 trace ideas from inception to payout, with fair attribution, coherence scoring, and 37 identity providers. No signup needed.",
   "type": "module",
   "bin": {