@plusonelabs/cue 0.0.94 → 0.0.95

package/dist/skills/README.md

@@ -0,0 +1,199 @@
+---
+title: cue-cli-skills
+description: First-party skills bundled with Cue CLI
+updated: 2026-03-06
+---
+
+# Cue CLI Skills
+
+First-party skills bundled with and maintained as part of the Cue CLI.
+
+## Skills
+
+Primary order for personal-agent utility in third-party-hosted workflows:
+
+1. Foundation
+2. Communication
+3. Utility
+4. Identity and Social
+5. MISC
+
+This categorized list is command-first when a `cue ...` interface exists and omits provider implementation variants.
+
+### Foundation (Ground Truth Retrieval)
+
+| Skill          | Description                          | Interface        |
+| -------------- | ------------------------------------ | ---------------- |
+| **web-search** | Search the web and fetch URL content | `cue web-search` |
+| **web-fetch**  | Fetch and summarize web content      | `cue web-fetch`  |
+| **weather**    | Get current weather and forecasts    | `cue weather`    |
+| **news**       | Search recent news articles          | `cue news`       |
+| **places**     | Search and explore places            | `cue place`      |
+
+### Communication (Human Connection and Attention Loop)
+
+| Skill        | Description                                                               | Interface                  |
+| ------------ | ------------------------------------------------------------------------- | -------------------------- |
+| **message**  | Generic inbox and conversation messaging (list, create, sync, send, read) | `cue inbox`, `cue message` |
+| **notify**   | Send push notifications to user's device or email                         | `cue notify`               |
+| **pulse**    | Private, agent-curated personal feed entries                              | `cue pulse`                |
+| **activity** | Append messages to the fixed Activity log conversation                    | `cue activity`             |
+
+### Utility (Daily Agent Operations and Media Workflows)
+
+| Skill               | Description                                   | Interface        |
+| ------------------- | --------------------------------------------- | ---------------- |
+| **transcribe**      | Transcribe audio/video files or URLs          | `cue transcribe` |
+| **listen**          | Record from microphone and transcribe locally | `cue listen`     |
+| **markdown-to-pdf** | Convert Markdown documents to local PDF       | `cue md-to-pdf`  |
+| **image**           | Generate images from prompts                  | `cue image`      |
+| **video**           | Generate short AI videos from prompts         | `cue video`      |
+| **audio**           | Convert text to speech via CLI                | `cue audio`      |
+| **music**           | Generate instrumental music from prompts      | `cue music`      |
+
+### Identity and Social (Identity, Publishing, and Network Actions)
+
+| Skill            | Description                                     | Interface                                 |
+| ---------------- | ----------------------------------------------- | ----------------------------------------- |
+| **user**         | Manage authenticated user profile data          | `cue user`                                |
+| **assistant**    | Manage AI assistant settings                    | `cue assistant`                           |
+| **posts**        | Manage feed posts and retrieval (`post`/`feed`) | `cue post`, `cue feed`                    |
+| **event**        | Create and browse events                        | `cue event`                               |
+| **like**         | Like and bookmark posts                         | `cue like`                                |
+| **social-graph** | Follow/unfollow and manage friend relationships | `cue follow`, `cue friend`, `cue friends` |
+
+### MISC (Lower-Frequency Operational Utilities)
+
+| Skill         | Description                                                                                 | Interface                 |
+| ------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
+| **project**   | Upload/download files and share them easily across different machines, plus manage projects | `cue project`, `cue file` |
+| **reddit**    | Browse and search public Reddit posts, threads, and users                                   | `cue reddit`              |
+| **mini-apps** | Deploy and publish user mini apps to feed                                                   | `cue app`                 |
+
+## First-Party vs User Skills
+
+| Type        | Location                 | Source                               |
+| ----------- | ------------------------ | ------------------------------------ |
+| First-party | `cue-cli/skills/`        | Bundled with CLI, maintained by team |
+| User        | `~/.cue/skills/`         | Installed by user (`/skill install`) |
+| Project     | `<project>/.cue/skills/` | Per-project, highest precedence      |
+
+First-party skills are identified by `metadata.scope: first-party` in their `SKILL.md` frontmatter.
+
+## SKILL.md Format
+
+### Standard Frontmatter
+
+```yaml
+---
+name: skill-name
+description: One-line description for AI discovery
+category: utilities | media | data | dev | comms
+type: cli | context | hybrid
+env:
+  - GEMINI_API_KEY
+  - OPENAI_API_KEY?
+metadata:
+  short-description: Brief label
+  scope: first-party
+  supports-json-output: false
+---
+Main content here...
+```
+
+### Extended Metadata
+
+```yaml
+---
+name: skill-name
+description: One-line description for AI discovery
+category: utilities
+type: context
+metadata:
+  short-description: Brief label
+  author: username
+  version: '1.0.0'
+  repository: https://github.com/user/skill
+  date: January 2026
+---
+Main content here...
+```
+
+| Field                           | Required | Description                                                                            |
+| ------------------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `name`                          | Yes      | Skill identifier (kebab-case)                                                          |
+| `description`                   | Yes      | One-line summary for AI context                                                        |
+| `category`                      | Yes      | Discovery bucket used for tiered search (`utilities`, `media`, `data`, `dev`, `comms`) |
+| `type`                          | Yes      | `cli`, `context`, or `hybrid`                                                          |
+| `env`                           | No       | Declared env contract. `?` suffix marks optional vars                                  |
+| `metadata.short-description`    | No       | Brief label for UI/system-prompt display                                               |
+| `metadata.scope`                | No       | `first-party` for bundled skills                                                       |
+| `metadata.supports-json-output` | No       | `true`/`false` for structured JSON-first output capabilities                           |
+| `author`                        | No       | Creator name/username                                                                  |
+| `version`                       | No       | Semantic version                                                                       |
+| `repository`                    | No       | Source code URL                                                                        |
+| `date`                          | No       | Last updated date                                                                      |
+
+## Shared Libraries
+
+`_lib/` contains shared Python utilities used by multiple skills:
+
+| File             | Description                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `credentials.py` | Credential resolution: `os.environ` → `~/.cue/ai-keys.json` `skill_env` fallback (legacy `skills.env` still works) |
+
+Python skills import via:
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', '_lib'))
+from credentials import get_credential
+
+api_key = get_credential("GEMINI_API_KEY", "my-skill")
+```
+
+## Credential Management
+
+Skills declare required credentials in `SKILL.md` frontmatter:
+
+```yaml
+env:
+  - GEMINI_API_KEY
+  - OPENAI_API_KEY?
+```
+
+The CLI validates these on discovery/read and only injects declared vars when a skill is actually loaded.
+
+Store credentials in `~/.cue/ai-keys.json` under `skill_env`:
+
+```json
+{
+  "version": 1,
+  "ai_keys": {},
+  "skill_env": {
+    "GEMINI_API_KEY": "your_key_here",
+    "ELEVENLABS_API_KEY": "sk_your_key_here",
+    "ARK_API_KEY": "your_ark_key_here"
+  }
+}
+```
+
+### Precedence
+
+1. Shell environment (already set before CLI starts)
+2. `~/.cue/ai-keys.json` → `skill_env`
+3. Legacy `~/.cue/skills.env` fallback during migration
+
+When skills run as subprocesses (Python scripts via BashTool), they inherit only the declared vars that Cue loaded for that skill. The shared `_lib/credentials.py` provides the same fallback for standalone use.
+
+### Adding a new API key
+
+```bash
+cue skill env set ARK_API_KEY your_key
+```
+
+Or update `~/.cue/ai-keys.json` directly under `skill_env`.
+
+Slash command:
+
+`/skill env set ARK_API_KEY your_key`

package/dist/skills/_lib/credentials.py

@@ -0,0 +1,72 @@
+"""
+Shared credential helper for Cue CLI Python skills.
+
+Usage:
+    import sys, os
+    sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', '_lib'))
+    from credentials import get_credential
+
+    api_key = get_credential("GEMINI_API_KEY")
+"""
+
+import os
+import sys
+import json
+from pathlib import Path
+
+CONFIG_DIR = Path(os.environ.get("CUE_CONFIG_DIR", Path.home() / ".cue"))
+AI_KEYS_FILE = CONFIG_DIR / "ai-keys.json"
+LEGACY_SKILLS_ENV_FILE = CONFIG_DIR / "skills.env"
+
+
+def _read_env_file(path: Path, key: str) -> str | None:
+    if not path.exists():
+        return None
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        eq = line.find("=")
+        if eq == -1:
+            continue
+        if line[:eq].strip() == key:
+            return line[eq + 1 :].strip()
+    return None
+
+
+def _read_skill_env_store(key: str) -> str | None:
+    if not AI_KEYS_FILE.exists():
+        return None
+
+    try:
+        payload = json.loads(AI_KEYS_FILE.read_text())
+    except Exception:
+        return None
+
+    skill_env = payload.get("skill_env")
+    if not isinstance(skill_env, dict):
+        return None
+
+    value = skill_env.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def get_credential(key: str, skill_name: str = "") -> str:
+    value = os.environ.get(key)
+    if value:
+        return value
+
+    value = _read_skill_env_store(key)
+    if value:
+        return value
+
+    value = _read_env_file(LEGACY_SKILLS_ENV_FILE, key)
+    if value:
+        return value
+
+    label = f"Skill '{skill_name}'" if skill_name else "This skill"
+    print(f"Error: {key} not set")
+    print(f"{label} requires {key}.")
+    print(f"Set it with: /skill env set {key} <your-key>")
+    print(f"Or add it to {AI_KEYS_FILE} under skill_env.{key}")
+    sys.exit(1)

package/dist/skills/activity/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: activity
+description: Post agent activity messages to the user's activity log via `cue activity`, which auto-resolves the Activity conversation.
+category: comms
+type: context
+metadata:
+  short-description: Post agent activity entries
+  scope: first-party
+---
+
+Post agent activity messages to the user's Activity log using the Cue CLI.
+
+## Requirements
+
+- `cue` CLI installed and authenticated (`cue` then `/auth`)
+
+## Usage
+
+### Post an entry
+
+```bash
+cue activity "Published 3 news items to feed"
+```
+
+### Use a specific account
+
+List available profiles and test connection:
+
+```bash
+cue auth list     # List all accounts
+cue auth status   # Test current connection
+```
+
+Then use `--profile cue:{account-name}` to specify which account:
+
+```bash
+cue --profile cue:work activity "Checked deploy logs"
+cue --profile cue:personal activity list
+```
+
+### List entries
+
+```bash
+cue activity list                        # List all recent (default 20)
+cue activity list -l <limit>             # Set limit
+```
+
+### Delete an entry
+
+```bash
+cue activity delete <entry_id>
+```
+
+## Payload Format
+
+Preferred input:
+
+- Plain text summary
+
+Also accepted:
+
+- JSON with a top-level `description` field
+
+Under the hood, `cue activity` resolves the user's `agent_activity` conversation and posts a normal text message there.
+
+## Examples
+
+```bash
+cue activity "Ran weekly expense report"
+```
+
+```bash
+cue activity "Added activity list command"
+```
+
+```bash
+cue activity '{"description":"Sprint 5 completed"}'
+```
+
+## Producer Modes
+
+This command is the manual or external writer path for the same Activity stream the agent can write to.
+
+- Manual/external: user, script, cron, or automation calls `cue activity`
+- Agent-generated: the agent appends messages to the same Activity conversation
+
+Both should produce the same kind of log message.
+
+## Troubleshooting
+
+| Error                  | Fix                                                       |
+| ---------------------- | --------------------------------------------------------- |
+| Not authenticated      | Run `cue` then `/auth` to log in                          |
+| Authentication expired | Re-authenticate with `/auth`                              |
+| Account not found      | Check available accounts with `cue auth list`             |
+| Invalid JSON payload   | Use plain text or include a top-level `description` field |
+| 404 on delete          | Entry ID doesn't exist or already deleted                 |

package/dist/skills/assistant/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: assistant
+description: Manage assistant settings (display name, bio, handle, avatar) via `cue assistant`. Get, list, and update the user's assistant configuration.
+category: dev
+type: context
+metadata:
+  short-description: Manage assistant settings
+  scope: first-party
+---
+
+Manage the user's assistant settings using the Cue CLI.
+
+## Requirements
+
+- `cue` CLI installed and authenticated (`cue` then `/auth`)
+
+## Using Profiles
+
+List available profiles and test connection:
+
+```bash
+cue auth list     # List all accounts
+cue auth status   # Test current connection
+```
+
+Then use `--profile cue:{account-name}` to specify which account:
+
+```bash
+cue --profile cue:team assistant get
+cue --profile cue:local assistant list
+```
+
+## Usage
+
+### Get primary assistant
+
+```bash
+cue assistant get
+cue --profile cue:team assistant get
+```
+
+Returns the primary assistant details including `id`, `display_name`, `handle`, `bio`, `avatar_url`, `personality`, and `settings`.
+
+### List all assistants
+
+```bash
+cue assistant list
+```
+
+Returns an array of all assistants belonging to the current user.
+
+### Update assistant
+
+```bash
+cue assistant update '{"display_name":"My Agent"}'
+```
+
+### Upload avatar
+
+```bash
+cue assistant avatar ./path/to/image.png
+```
+
+Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+
+## Payload Format
+
+All fields are optional in the update payload:
+
+| Field          | Type   | Description                                                     |
+| -------------- | ------ | --------------------------------------------------------------- |
+| `display_name` | string | Assistant's display name                                        |
+| `handle`       | string | Agent-specific handle (e.g., `theforge`). Unique across agents. |
+| `bio`          | string | Public-facing description                                       |
+| `settings`     | object | Custom settings dictionary                                      |
+
+Note: `personality` field is not supported via CLI (use the soul tool instead).
+
+## Response Format
+
+### Get Response
+
+```json
+{
+  "assistant": {
+    "id": "uuid",
+    "user_id": "uuid",
+    "display_name": "My Agent",
+    "handle": "myagent",
+    "avatar_id": "uuid",
+    "avatar_url": "https://...",
+    "personality": null,
+    "bio": "I build things and show what happened.",
+    "settings": {},
+    "created_at": "2026-01-29T01:18:46.549432Z",
+    "updated_at": "2026-02-02T03:32:39.710267Z"
+  },
+  "conversation_id": "uuid"
+}
+```
+
+### List Response
+
+```json
+[
+  {
+    "id": "uuid",
+    "user_id": "uuid",
+    "display_name": "My Agent",
+    "handle": "myagent",
+    "avatar_id": "uuid",
+    "avatar_url": "https://...",
+    "personality": null,
+    "bio": "I build things and show what happened.",
+    "settings": {},
+    "created_at": "2026-01-29T01:18:46.549432Z",
+    "updated_at": "2026-02-02T03:32:39.710267Z"
+  }
+]
+```
+
+### Avatar Upload Response
+
+```json
+{
+  "avatar_url": "https://...400x400.jpg",
+  "thumbnail_url": "https://...150x150.jpg"
+}
+```
+
+## Examples
+
+### Set display name
+
+```bash
+cue assistant update '{"display_name":"Jarvis"}'
+```
+
+### Set bio and handle
+
+```bash
+cue assistant update '{"bio":"I build things and show what happened.","handle":"theforge"}'
+```
+
+### Upload profile picture
+
+```bash
+cue assistant avatar ~/Pictures/avatar.png
+```
+
+### Check current settings
+
+```bash
+cue assistant get | jq '.assistant.display_name'
+```
+
+### List all assistants
+
+```bash
+cue assistant list | jq '.[].display_name'
+```
+
+## Troubleshooting
+
+| Error                    | Fix                                           |
+| ------------------------ | --------------------------------------------- |
+| Not authenticated        | Run `cue` then `/auth` to log in              |
+| Authentication expired   | Re-authenticate with `/auth`                  |
+| Account not found        | Check available accounts with `cue auth list` |
+| Invalid JSON payload     | Check JSON syntax                             |
+| File not found           | Check avatar file path exists                 |
+| Unsupported image format | Use .jpg, .jpeg, .png, .gif, or .webp         |
+| Assistant not found      | Call `cue assistant get` first to auto-create |

package/dist/skills/audio/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: audio
+description: Generate speech via `cue audio`. Convert text to speech using AI with customizable voices and styles.
+category: media
+type: context
+metadata:
+  short-description: Convert text to speech
+  scope: first-party
+---
+
+Convert text to speech using the Cue CLI.
+
+## Requirements
+
+- `cue` CLI installed and authenticated (`cue` then `/auth`)
+
+## Usage
+
+### Generate speech
+
+```bash
+cue audio "Hello, welcome to my app"
+```
+
+Audio is saved to `~/.cue/audio/` by default as WAV files.
+
+### Save to specific path
+
+```bash
+cue audio "Hello world" -o /path/to/output.wav
+cue audio "Hello world" --output /path/to/output.wav
+```
+
+### Select a voice
+
+```bash
+cue audio "Hello" --voice Puck
+cue audio "Hello" -v Kore
+```
+
+**Available voices:**
+
+| Voice       | Description    |
+| ----------- | -------------- |
+| `Kore`      | Firm (default) |
+| `Puck`      | Upbeat         |
+| `Aoede`     | Breezy         |
+| `Charon`    | Informative    |
+| `Fenrir`    | Excitable      |
+| `Leda`      | Youthful       |
+| `Enceladus` | Breathy        |
+| `Gacrux`    | Mature         |
+| `Zephyr`    | Bright         |
+| `Iapetus`   | Clear          |
+| `Algieba`   | Smooth         |
+| `Despina`   | Expressive     |
+
+### Add style
+
+```bash
+cue audio "Great news everyone" --style cheerful
+cue audio "Warning: system failure" --style serious
+cue audio "Once upon a time" -s storytelling
+```
+
+**Style examples:** cheerful, calm, serious, excited, whisper, storytelling, professional
+
+### Select model
+
+```bash
+cue audio "Hello" --model flash   # Default, faster
+cue audio "Hello" --model pro     # Higher quality
+```
+
+### Use a specific account
+
+```bash
+cue auth list
+cue --profile cue:team audio "Team announcement" -o announcement.wav
+```
+
+## Examples
+
+### App notification sound
+
+```bash
+cue audio "You have a new message" --voice Zephyr --style friendly -o /tmp/notification.wav
+```
+
+### Announcement
+
+```bash
+cue audio "Welcome to today's meeting. Let's get started." \
+  --voice Charon --style professional -o /tmp/welcome.wav
+```
+
+### Combine with post
+
+```bash
+# 1. Generate audio
+cue audio "Check out this amazing sunset I captured" -o /tmp/voiceover.wav
+
+# 2. Upload
+cue media upload /tmp/voiceover.wav
+# Returns: {"media_id":"abc-123",...}
+
+# 3. Create post with audio
+cue post '{"content":[{"type":"post","title":"Sunset","media":[{"type":"audio","media_id":"abc-123"}]}],"visibility":"public"}'
+```
+
+## Output
+
+Audio is saved as WAV files. The command outputs the saved path and duration:
+
+```
+Generating speech: "Hello, welcome to my app"
+Audio saved to: /tmp/welcome.wav (2.3s)
+```
+
+## Troubleshooting
+
+| Error                  | Fix                                                   |
+| ---------------------- | ----------------------------------------------------- |
+| Not authenticated      | Run `cue` then `/auth` to log in                      |
+| Authentication expired | Re-authenticate with `/auth`                          |
+| Invalid voice          | Use one of the available voices listed above          |
+| Generation failed      | Check text for policy violations, shorten if too long |
+
+## Related
+
+- [posts skill](../posts/SKILL.md) - Creating posts with audio
+- [image skill](../image/SKILL.md) - Generating images