@sage-protocol/cli 0.8.15 → 0.8.16

package/README.md

@@ -1,295 +1,185 @@
 # Sage CLI
 
-Command-line interface for the Sage Protocol. Create, manage, and publish AI prompt libraries with on-chain governance or as personal collections.
+CLI for the Sage Protocol. Install AI prompts and skills, create prompt libraries, and publish with on-chain governance.
 
 ```bash
 npm i -g @sage-protocol/cli
-sage --help
 ```
 
-## Quick Start
+## Zero-Config Start (Privy Default)
 
-### Personal/Vault Library (No Governance)
-
-Create a wallet-owned library for your prompts without DAO overhead:
+**Privy wallet is the default** - no local keystore or seed phrase needed. Just install and go:
 
 ```bash
-# 1. Connect your wallet
-# Privy is the default for npm installs (no local keystore required)
-# App ID is baked in; no secret is required when using the web relay (default)
-sage wallet connect
-
-# 2. Create a personal library
-sage library vault create --name "My Prompts"
+# Install a skill immediately
+sage install build-web3
 
-# 3. Push prompts to your library
-sage library vault push <libraryId> --dir ./prompts
+# Or connect your wallet first (opens browser)
+sage wallet connect
 
-# 4. List your libraries
-sage library vault list
+# Get testnet tokens
+sage sxxx faucet
 ```
 
-### DAO Library (With Governance)
-
-Create a governed library with token-based voting:
+## Install Skills & Prompts
 
 ```bash
-# 1. Quick setup: scan prompts, upload, create DAO, register
-sage library quickstart --name "My DAO Library" --from-dir ./prompts
-
-# 2. Or step-by-step:
-sage prompts init                    # Initialize workspace
-sage prompts new my-prompt           # Create a prompt
-sage prompts publish                 # Upload and propose update
-```
-
-### Install Prompts from Others
+# From the Sage platform
+sage install build-web3
+sage install solidity-audit
 
-```bash
-# From a DAO
+# From a DAO library
 sage install 0x1234...abcd
-sage install my-library
 
 # From IPFS
-sage install QmXyz...
+sage install bafkrei...
 
 # From GitHub
 sage install github:user/repo
-```
 
-Note: autonomous agents use the A2A JSON‑RPC surface (`/a2a/dao/:subdao`) for paid, trust‑ranked discovery. The CLI continues to use public discovery/content endpoints.
-
-## Command Reference
-
-### Library Management
-
-| Command | Description |
-|---------|-------------|
-| `sage library quickstart` | Create library + DAO in one command |
-| `sage library info` | Show library info for a DAO |
-| `sage library fork <source>` | Fork an existing library |
-| `sage library personal create` | Create a personal (wallet-owned) library |
-| `sage library personal list` | List your personal libraries |
-| `sage library personal push` | Push files to a personal library |
-| `sage library personal delete` | Delete a personal library |
-| `sage library vault ...` | Alias for personal libraries (clearer SIWE vault naming) |
-
-### Prompt Workspace
-
-| Command | Description |
-|---------|-------------|
-| `sage prompts init` | Initialize a prompt workspace |
-| `sage prompts new <key>` | Create a new prompt/skill |
-| `sage prompts list` | List all prompts in workspace |
-| `sage prompts publish` | Build manifest and propose update |
-| `sage prompts sync` | Sync with on-chain state |
-| `sage prompts import <source>` | Import from GitHub/on-chain |
-| `sage prompts search <query>` | Search prompts |
-
-### Personal Prompts
-
-| Command | Description |
-|---------|-------------|
-| `sage personal create` | Create a personal registry |
-| `sage personal publish <key>` | Publish a free prompt |
-| `sage personal list` | List personal prompts |
-| `sage personal premium publish` | Publish paid content |
-| `sage personal premium buy` | Purchase a license |
-| `sage personal premium access` | Decrypt purchased content |
-| `sage personal my-licenses` | View owned licenses |
-
-### Wallet & Config
-
-| Command | Description |
-|---------|-------------|
-| `sage wallet connect` | Connect a wallet (Cast, Privy, WalletConnect) |
-| `sage wallet balance` | Show wallet balance |
-| `sage config show` | Show current configuration |
-| `sage config ipfs onboard` | Configure IPFS/pinning |
-| `sage secret set <name>` | Store a secret in keychain |
+# List what you have installed
+sage list
+```
 
-### NPM Install Setup (Privy)
+## Create a Personal Library
 
-For npm installs (running outside a repo), put Privy credentials in a global env file:
+No governance overhead - just publish under your wallet:
 
 ```bash
-mkdir -p ~/.sage
-cat >> ~/.sage/.env << 'EOF'
-PRIVY_APP_ID=your_app_id
-PRIVY_APP_SECRET=your_app_secret
-EOF
-```
+# Create library
+sage library personal create --name "My Prompts"
 
-Then:
+# Push your prompts
+sage library personal push <libraryId> --from-dir ./prompts
 
-```bash
-SAGE_WALLET_TYPE=privy sage wallet connect
+# List your libraries
+sage library personal list
 ```
 
-### Governance
+## Create a Governed DAO Library
 
-| Command | Description |
-|---------|-------------|
-| `sage gov propose` | Create a governance proposal |
-| `sage gov vote <proposalId>` | Vote on a proposal |
-| `sage gov queue <proposalId>` | Queue a passed proposal |
-| `sage gov execute <proposalId>` | Execute a queued proposal |
-| `sage proposals list` | List proposals for current DAO |
-
-### Reputation
-
-| Command | Description |
-|---------|-------------|
-| `sage reputation check <address>` | Check trust signals (badges, contributions) |
-| `sage reputation status <address>` | Author metrics (revenue, purchases, consumers) |
-| `sage reputation leaderboard` | Top authors by revenue |
-| `sage reputation achievements <address>` | Achievement badges earned |
-
-## Personal/Vault Libraries
-
-Personal libraries are wallet-owned collections that don't require DAO governance. They're ideal for:
-
-- **Individual creators** who want to publish prompts under their own identity
-- **Quick iteration** without governance delays
-- **Premium content** with on-chain licensing via Lit Protocol
-
-### Create and Manage
+For team/community libraries with on-chain voting:
 
 ```bash
-# Create a new vault library (alias of personal)
-sage library vault create --name "My AI Prompts" --description "Curated prompts for development"
-
-# View your libraries
-sage library vault list
+# One command: scan prompts, upload, create DAO, register
+sage library quickstart --name "Team Library" --from-dir ./prompts
 
-# Push content from a directory
-sage library vault push lib_abc123 --dir ./my-prompts
-
-# Get library details
-sage library vault info lib_abc123
-
-# Delete a library
-sage library vault delete lib_abc123
+# Or step-by-step
+sage prompts init
+sage prompts new my-prompt
+sage prompts publish
 ```
 
-### Premium Content
+## First-Time Setup (Optional)
 
-Sell encrypted prompts with on-chain licensing:
+Privy handles auth automatically. For advanced setup:
 
 ```bash
-# Publish premium content (encrypted via Lit Protocol)
-sage personal premium publish my-prompt \
-  --file prompts/valuable-prompt.md \
-  --price 100 \
-  --name "Advanced Prompt" \
-  --description "High-value prompt template"
-
-# Check pricing
-sage personal premium price <creator> <key>
-
-# Buy a license
-sage personal premium buy <creator> <key> --auto-approve
-
-# Access purchased content
-sage personal premium access <creator> <key> --out decrypted.md
-
-# View your licenses
-sage personal my-licenses
+sage init                    # Interactive setup wizard
+sage doctor                  # Check your environment
+sage wizard                  # Guided tutorial
 ```
 
-## IPFS & Pinning
-
-The CLI uses the Sage IPFS worker by default:
-
-- **Gateway**: `https://ipfs.dev.sageprotocol.io/ipfs`
-- **Worker**: `https://api.sageprotocol.io`
+## Claude Code Integration
 
 ```bash
-# Configure IPFS
-sage config ipfs onboard
-
-# Upload content
-sage ipfs upload ./my-file.md
-
-# Pin existing content
-sage ipfs pin <cid>
+# Init with skill support
+sage init --with-skill
 
-# Check credits
-sage ipfs credits
+# Install skills for Claude Code
+sage install build-web3
+sage prompts import-skill solidity-audit
 ```
 
-### Credits
+---
 
-```bash
-# Show credit balance
-sage ipfs credits
+## Command Reference
 
-# Buy credits (opens checkout)
-sage ipfs buy-credits
+### Installation & Skills
 
-# Pin with credits
-sage ipfs pin <cid>
-```
+| Command | Description |
+|---------|-------------|
+| `sage install <source>` | Install from DAO, IPFS, or GitHub |
+| `sage list` | List installed prompts/skills |
+| `sage update [key]` | Update installed content |
+| `sage skill add <path>` | Add local skill to Claude Code |
 
-## Configuration
+### Wallet & Tokens
 
-Configuration is stored in `.sage/config.json` (project) or `~/.config/sage` (global).
+| Command | Description |
+|---------|-------------|
+| `sage wallet` | Show wallet info (Privy default) |
+| `sage wallet connect` | Connect wallet (opens browser) |
+| `sage sxxx faucet` | Get testnet SXXX tokens |
+| `sage sxxx balance` | Check SXXX balance |
+| `sage sxxx delegate-self` | Enable voting power |
 
-```bash
-# Show all config
-sage config show --all
+### Libraries
 
-# Set RPC endpoint
-sage config set-rpc https://base-sepolia.publicnode.com --chain-id 84532
+| Command | Description |
+|---------|-------------|
+| `sage library personal create` | Create wallet-owned library |
+| `sage library personal push` | Push content to library |
+| `sage library personal list` | List your libraries |
+| `sage library quickstart` | Create DAO library in one command |
 
-# Manage profiles
-sage config profile list
-sage config profile use <name>
-```
+### Prompts
 
-### Secrets
+| Command | Description |
+|---------|-------------|
+| `sage prompts init` | Initialize workspace |
+| `sage prompts new <key>` | Create new prompt |
+| `sage prompts publish` | Publish to DAO |
+| `sage prompts sync` | Sync with on-chain state |
 
-Secrets are stored in your OS keychain:
+### DAO & Governance
 
-```bash
-sage secret set pinata.jwt
-sage secret get pinata.jwt
-sage secret list
-sage secret delete <name>
-```
+| Command | Description |
+|---------|-------------|
+| `sage dao list` | List DAOs |
+| `sage dao info <addr>` | Show DAO details |
+| `sage proposals inbox` | Active proposals |
+| `sage gov vote <id>` | Vote on proposal |
 
-In CI, set `SAGE_SECRETS_BACKEND=env` and use environment variables.
+### IPFS
 
-## Claude Code Integration
+| Command | Description |
+|---------|-------------|
+| `sage ipfs upload <file>` | Upload to IPFS |
+| `sage ipfs download <cid>` | Download (prompts, skills, raw) |
+| `sage ipfs pins` | List pinned content |
 
-Initialize a project with Claude Code skill support:
+### Config
 
-```bash
-sage init --with-skill
-```
+| Command | Description |
+|---------|-------------|
+| `sage config show` | Show configuration |
+| `sage context` | Show DAO context |
+| `sage doctor` | Diagnose environment |
 
-This creates:
-```
-.claude/
-├── skills/build-web3/
-│   ├── SKILL.md
-│   └── workflows/
-└── commands/build-web3.md
+## Aliases
 
-CLAUDE.md
-```
+| Full | Short |
+|------|-------|
+| `sage library` | `sage l` |
+| `sage governance` | `sage gov` |
+| `sage wallet` | `sage w` |
+| `sage sxxx` | `sage token` |
+
+## Premium Content
 
-Import skills from the platform:
+Sell encrypted prompts with Lit Protocol licensing:
 
 ```bash
-sage prompts import-skill <name>
-sage install build-web3
+sage personal premium publish my-prompt --file ./prompt.md --price 100
+sage personal premium buy <creator> <key>
+sage personal premium access <creator> <key> --out decrypted.md
 ```
 
-## Documentation
+## Links
 
-- [Development Guide](docs/DEVELOPMENT.md) - Setup, testing, and contributing
-- [Full Docs](https://docs.sageprotocol.io) - Complete documentation
+- [Documentation](https://docs.sageprotocol.io)
+- [GitHub](https://github.com/sage-protocol/cli)
 
 ## License
 

package/dist/cli/commands/ipfs.js

@@ -321,7 +321,7 @@ function register(program) {
     )
     .addCommand(
       new Command('download')
-        .description('Download prompt from IPFS')
+        .description('Download content from IPFS (prompts, skills, libraries, or raw files)')
         .argument('<cid>', 'IPFS CID to download')
         .option('-o, --output <file>', 'Output file path')
         .option('-g, --gateway <url>', 'Preferred IPFS gateway (reads)', process.env.SAGE_IPFS_GATEWAY)

package/dist/cli/ipfs-manager.js

@@ -533,32 +533,138 @@ class IPFSManager {
 
   async downloadPrompt(cid, outputPath) {
     try {
-      const downloaded = await withSpinner('Downloading prompt from IPFS', async () => {
+      const downloaded = await withSpinner('Downloading content from IPFS', async () => {
         let prompt = this.prompts.get(cid);
+        let contentType = 'prompt';
+
         if (!prompt) {
+          // First try to fetch as JSON (prompt/skill format)
           const data = await this.#withBackoff(() => this.client.downloadJson({ cid }).catch(() => null), { retries: Number(process.env.SAGE_IPFS_FETCH_RETRIES || 2), baseMs: Number(process.env.SAGE_IPFS_FETCH_BACKOFF_MS || 400) });
+
           if (data) {
-            prompt = {
-              name: data.name || 'Downloaded Prompt',
-              description: data.description || 'Downloaded from IPFS',
-              content: data.content || JSON.stringify(data),
-              timestamp: data.timestamp || Date.now(),
-              filePath: 'ipfs-download',
-            };
+            // Detect content type based on structure
+            if (data.skills && Array.isArray(data.skills)) {
+              // Library manifest with skills
+              contentType = 'library';
+              prompt = {
+                name: data.name || 'Downloaded Library',
+                description: data.description || 'Library manifest from IPFS',
+                content: JSON.stringify(data, null, 2),
+                timestamp: data.timestamp || Date.now(),
+                filePath: 'ipfs-download',
+                metadata: { type: 'library', skillCount: data.skills.length, promptCount: data.prompts?.length || 0 }
+              };
+            } else if (data.content && (data.content.includes('# ') || data.content.includes('```'))) {
+              // Skill format (markdown content)
+              contentType = 'skill';
+              prompt = {
+                name: data.name || data.key || 'Downloaded Skill',
+                description: data.description || 'Skill from IPFS',
+                content: data.content,
+                timestamp: data.timestamp || Date.now(),
+                filePath: 'ipfs-download',
+                metadata: { type: 'skill', tags: data.tags }
+              };
+            } else if (data.name && data.content) {
+              // Standard prompt format
+              contentType = 'prompt';
+              prompt = {
+                name: data.name,
+                description: data.description || 'Downloaded from IPFS',
+                content: data.content,
+                timestamp: data.timestamp || Date.now(),
+                filePath: 'ipfs-download',
+              };
+            } else {
+              // Unknown JSON structure - save as raw JSON
+              contentType = 'json';
+              prompt = {
+                name: 'Downloaded Content',
+                description: 'Raw JSON from IPFS',
+                content: JSON.stringify(data, null, 2),
+                timestamp: Date.now(),
+                filePath: 'ipfs-download',
+                metadata: { type: 'json', keys: Object.keys(data) }
+              };
+            }
             this.prompts.set(cid, prompt);
+          } else {
+            // Try to fetch as raw text via gateway
+            const gatewayUrls = this.buildGatewayUrls(cid);
+            let rawContent = null;
+
+            for (const url of gatewayUrls) {
+              try {
+                const axios = require('axios');
+                const response = await axios.get(url, { timeout: 15000, responseType: 'text' });
+                if (response.data) {
+                  rawContent = typeof response.data === 'string' ? response.data : JSON.stringify(response.data);
+                  break;
+                }
+              } catch (_) {
+                // Try next gateway
+              }
+            }
+
+            if (rawContent) {
+              contentType = 'raw';
+              prompt = {
+                name: 'Downloaded Content',
+                description: 'Raw content from IPFS',
+                content: rawContent,
+                timestamp: Date.now(),
+                filePath: 'ipfs-download',
+                metadata: { type: 'raw', size: rawContent.length }
+              };
+              this.prompts.set(cid, prompt);
+            }
           }
         }
-        if (!prompt) throw new Error(`Prompt with CID ${cid} not found`);
-        const finalOutputPath = outputPath || `${prompt.name}.txt`;
+
+        if (!prompt) {
+          throw new Error(`Content with CID ${cid} not found. The CID may be invalid or the content may have expired.`);
+        }
+
+        // Determine file extension based on content type
+        let extension = '.txt';
+        if (contentType === 'skill') extension = '.md';
+        else if (contentType === 'library' || contentType === 'json') extension = '.json';
+
+        const safeName = prompt.name.replace(/[^a-zA-Z0-9-_]/g, '-').toLowerCase();
+        const finalOutputPath = outputPath || `${safeName}${extension}`;
         fs.writeFileSync(finalOutputPath, prompt.content);
-        return { prompt, finalOutputPath };
+
+        return { prompt, finalOutputPath, contentType };
       }, { successText: () => 'Downloaded' });
-      this.log('📝 Name:', downloaded.prompt.name);
+
+      // Show appropriate output based on content type
+      const typeLabels = {
+        prompt: '📝 Prompt',
+        skill: '🛠️  Skill',
+        library: '📚 Library',
+        json: '📄 JSON',
+        raw: '📦 Raw Content'
+      };
+
+      this.log(`${typeLabels[downloaded.contentType] || '📄 Content'}: ${downloaded.prompt.name}`);
       this.log('📄 Description:', downloaded.prompt.description);
       this.log('📁 Saved to:', downloaded.finalOutputPath);
+
+      // Show helpful hints based on content type
+      if (downloaded.contentType === 'skill') {
+        this.log(colors.yellow('\n💡 Tip: To install this skill, run:'));
+        this.log(`   sage skill add ${downloaded.finalOutputPath}`);
+      } else if (downloaded.contentType === 'library') {
+        const meta = downloaded.prompt.metadata || {};
+        this.log(`📊 Contains: ${meta.promptCount || 0} prompts, ${meta.skillCount || 0} skills`);
+      } else if (downloaded.contentType === 'raw') {
+        this.log(colors.yellow('\n⚠️  Note: This content is not in Sage prompt/skill format.'));
+        this.log('   It has been saved as raw text.');
+      }
+
       return downloaded.finalOutputPath;
     } catch (error) {
-      console.error('❌ Failed to download prompt:', error.message);
+      console.error('❌ Failed to download content:', error.message);
       throw error;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/cli",
-  "version": "0.8.15",
+  "version": "0.8.16",
   "description": "Sage Protocol CLI for managing AI prompt libraries",
   "bin": {
     "sage": "./bin/sage.js"