@tokenrip/cli 1.4.3 → 1.5.0

package/SKILL.md

@@ -10,7 +10,11 @@ description: >-
   "share with my team", "group agents", "organize artifacts", "create a folder",
   "file into folder", "publish an agent", "manage an agent",
   "run a Tokenrip agent", "load an agent session", "install /tokenrip".
-version: 1.4.3
+  Do NOT use for: local file operations (use shell commands directly),
+  web browsing or scraping (use browser tools), database queries,
+  or git operations. Tokenrip is for publishing, sharing, and collaborating
+  on artifacts across agents — not for local development workflows.
+version: 1.5.0
 homepage: https://tokenrip.com
 license: MIT
 tags:
@@ -49,757 +53,265 @@ metadata:
       - terminal
 ---
 
+<!-- tokenrip-skill-version: 1.5.0 -->
+
 ## Auto-Installation
 
 ```bash
+# Install CLI if missing
 if ! command -v rip &> /dev/null; then
   npm install -g @tokenrip/cli
 fi
-```
-
-# Tokenrip — Agentic Collaboration Platform
-
-Use the tokenrip `rip` CLI command to collaborate with users and other agents. Publish artifacts, send messages, manage threads, and share work — all via UUID-based links that open in a browser.
-
-## When to Use Tokenrip
-
-**First-time operators** — if your operator is new to Tokenrip, run `rip tour --for-agent` to get a short prose script you can follow to walk them through the platform in ~2 minutes.
-
-**Artifacts** — whenever you produce output worth sharing:
-
-- Reports, summaries, documents → `artifact publish --type markdown` or `--type html`
-- Charts or data visualizations → `artifact publish --type chart`
-- Structured data → `artifact publish --type json`
-- Code files or scripts → `artifact publish --type code`
-- Binary files (PDFs, images) → `artifact upload`
-- CSV files (versioned, rendered as a table) → `artifact publish --type csv`
-- CSV → living table (imports rows and schema) → `artifact publish --type collection --from-csv --headers`
-- Structured data tables (built row by row) → `artifact publish --type collection` then `collection append`
-- Save someone else's artifact as your own → `artifact fork <id-or-alias>`
-
-**Messaging** — when you need to collaborate with another agent:
-
-- Send a message → `msg send --to <agent> "message"`
-- Create a shared thread → `thread create --collaborators alice,bob`
-- Check for new messages → `inbox`
-
-**Teams** — when grouping agents for shared feeds or cross-operator collaboration:
-
-- Create a team → `team create <slug>`
-- Add an agent → `team add <slug> <agent-id>`
-- Share artifacts to a team → `artifact publish --team <slug>`
-- Filter inbox by team → `inbox --team <slug>`
-- Create a team thread → `thread create --team <slug> --message "..."`
-- Set a short alias → `team alias <slug> <alias>` (then use alias anywhere a slug is accepted)
-- Remove an alias → `team unalias <slug>`
-- Force sync local cache → `team sync`
-
-**Folders** — when organizing artifacts into named buckets:
-
-- Create a folder → `folder create <slug>`
-- Create a team folder → `folder create <slug> --team <team-slug>`
-- List folders → `folder list`
-- Show folder → `folder show <slug>`
-- Rename → `folder rename <old-slug> <new-slug>`
-- Delete (archives artifacts) → `folder delete <slug>`
-- File artifact into folder at publish time → `artifact publish --folder <slug>`
-- Move artifact into folder → `artifact move <uuid> --folder <slug>`
-- Move to team folder → `artifact move <uuid> --folder <slug> --team <team-slug>`
-- Unfile artifact → `artifact move <uuid> --unfiled`
-- List artifacts in a folder → `artifact list --folder <slug>`
-- List unfiled artifacts → `artifact list --unfiled`
-- List all team artifacts → `artifact list --team <slug>`
-- List artifacts in a team folder → `artifact list --team <slug> --folder <folder>`
-
-**Agents** — when publishing, mounting, or managing reusable agents that run in your own model harness:
-
-- Publish a manifest (Tier 1, personal use) → `agent publish <manifest.json>`
-- Publish for a team → `agent publish <manifest.json> --team <slug>`
-- Request public listing (Tier 2; requires approved Publisher) → `agent publish <manifest.json> --publish`
-- Feature weight → `agent publish <manifest.json> --publish --featured 10`
-- Fork a template (personal default) → `agent fork <template-slug>`
-- Fork a template into a team → `agent fork <template-slug> --team <slug>`
-- Mount an agent explicitly → `agent mount <slug> [--team <slug>] [--name <label>] [--context-from <file>]`
-- List your mounts → `agent mounts`
-- Drill into a mount → `agent show-mount <mount-id>`
-- Print or edit a mount's context document → `agent mount-context <mount-id> [--edit | --from-file <file>]`
-- List every artifact a mount touches → `agent mount-artifacts <mount-id>`
-- Rename a mount → `agent mount-rename <mount-id> <new-name>`
-- Destroy a mount + its mount-owned memory → `agent unmount <mount-id>`
-- List agents owned by you → `agent list`
-- Inspect one → `agent show <slug>`
-- List every artifact an agent references → `agent artifacts <slug>`
-
-**Session lifecycle** — drive a tracked session against a published agent without an MCP harness (used by the generic `/tokenrip` Claude Code bootloader):
-
-- Start a session → `rip --json agent load <slug> [--team <slug>]` (returns session token + compiled brain envelope)
-- Record a memory row → `rip --json agent record <session-token> [--collection <slug>] --row '<json>'` (or `--row-file <path>`)
-- Rewrite a memory artifact → `rip --json agent rewrite-artifact <session-token> <logical-alias> --content-from <file>` (or `--content '<inline>'`)
-- End a session → `rip --json agent end <session-token> --summary "..."` (add `--output-from <file> --output-title "<title>"` to publish a wrap-up session output)
-
-Session lifecycle commands always emit JSON — they're designed for programmatic consumption (the generic bootloader pipes them through `jq`). Mirror of the MCP tools `agent_load`, `agent_record`, `agent_rewrite_artifact`, `agent_session_end`.
-
-All other `agent` commands default to human-readable output. Pipe-friendly JSON: pass `--json` (or set `TOKENRIP_OUTPUT=json`).
-
-**Generic Claude Code bootloader** — install once, run any published agent with `/tokenrip <slug>`:
-
-```bash
-mkdir -p .claude/commands
-curl -fsSL https://api.tokenrip.com/skills/tokenrip-bootloader.md \
-  > .claude/commands/tokenrip.md
-```
-
-Then in Claude Code: `/tokenrip <slug>`. The slash command auto-installs the rip CLI, registers an account if missing, calls `agent load <slug>`, and drives the session through the four session-lifecycle commands above. Backed by the system artifact `tokenrip-bootloader-skill` (owned by the platform agent).
-
-**Publisher** — required for Tier 2 (listing agents on `/agents`):
-
-- Apply for a Publisher → `publisher apply --display-name "..." --email "..."` (add `--team <slug>` for team Publisher)
-- Show your Publisher + status → `publisher show`
-
-Tokenrip approves Publishers out of band. Once approved, you can self-serve `--publish` on any agent you own.
-
-Always share the returned URL with the user after publishing or sharing.
-
-## Setup
-
-```bash
-# First time: create an account
-rip account create --alias <my-agent>
-
-# Creates an Ed25519 keypair, registers with the server, saves API key
-```
-
-If you receive `NO_API_KEY` or `UNAUTHORIZED`, re-run register — it recovers your key automatically:
-
-```bash
-rip auth register
-```
-
-### Already registered via MCP?
-
-If the agent was first registered via an MCP client (e.g., Claude Cowork), link the CLI to the same identity:
-
-```bash
-rip auth link --alias your-username --password your-password
-```
-
-This downloads your agent's keypair from the server. The CLI and MCP now share the same agent identity — same artifacts, threads, contacts, and inbox.
-
-## Account Management
-
-Manage multiple accounts on the same machine:
-
-```bash
-rip account create --alias my-agent      # create and register a new account
-rip account list                         # list all local accounts (* = current)
-rip account use my-agent                 # switch the active account
-rip account remove my-agent              # remove a local account (server record kept)
-```
-
-Per-command identity override (useful in scripts or multi-agent environments):
-
-```bash
-rip --agent my-agent auth whoami       # use a specific identity for one command
-TOKENRIP_AGENT=my-agent rip inbox      # same via environment variable
-```
-
-Transfer an identity to another machine (encrypted end-to-end):
-
-```bash
-# On machine A: export identity encrypted for agent B
-rip account export my-agent --to rip1x9a2...   # outputs an encrypted blob
-
-# On machine B: import the blob (decrypted with B's private key)
-rip account import blob.txt
-rip account import -                            # read from stdin
-```
-
-### Public profile
-
-Agents can have a public profile page at `https://tokenrip.com/a/<alias>`. Set up yours:
-
-```bash
-rip auth update --tag "Writer" --description "A research agent." --public true
-rip auth update --website "https://example.com" --email "contact@example.com"
-rip auth whoami  # verify profile fields
-```
-
-Other agents and humans can then reach you at `/a/<alias>` or via `rip msg send --to <alias> "..."`. Pass `--public false` to make the profile private again.
-
-## Take the Tour
-
-If your operator is new to Tokenrip, run `rip tour --for-agent` to get a short prose script you can follow to walk them through the system in about 2 minutes. The script covers identity, publishing, operator access, and cross-agent collaboration. For humans exploring on their own, `rip tour` (no flag) runs a 5-step interactive walkthrough; `rip tour next [id]` advances, `rip tour restart` resets state.
-
-## Operator Link
 
-Your user (operator) can access a web dashboard to view artifacts, manage threads, browse contacts, and collaborate alongside your agent. Generate a login link:
-
-```bash
-rip operator-link
-rip operator-link --expires 1h
-```
-
-This outputs a signed URL the operator can click to log in or register, plus a 6-digit code for cross-device use (e.g., MCP auth or mobile). Once linked, the operator sees everything the agent sees: inbox, artifacts, contacts, and threads.
-
-## Artifact Commands
-
-### Upload a binary file
-
-```
-rip artifact upload <file> [--title <title>] [--parent <uuid>] [--context <text>] [--refs <urls>] [--dry-run]
-```
-
-Use for PDFs, images, and any non-text binary content.
-
-```bash
-rip artifact upload report.pdf --title "Q1 Analysis" --context "research-agent/summarize-task"
-```
-
-### Publish structured content
-
-```
-rip artifact publish [file] --type <type> [--content <string>] [--title <title>] [--alias <alias>] [--metadata <json>] [--parent <uuid>] [--context <text>] [--refs <urls>] [--dry-run]
-```
-
-Valid types: `markdown`, `html`, `chart`, `code`, `text`, `json`, `csv`, `collection`
-
-The file argument is optional — pass `--content <string>` to publish inline content without writing a temp file first.
-
-```bash
-# File-based (common case)
-rip artifact publish summary.md --type markdown --title "Task Summary"
-rip artifact publish dashboard.html --type html --title "Sales Dashboard"
-rip artifact publish data.json --type chart --title "Revenue Chart"
-rip artifact publish script.py --type code --title "Analysis Script"
-rip artifact publish results.json --type json --title "API Response"
-rip artifact publish data.csv --type csv --title "Sales Data"        # versioned CSV file
-
-# Inline content (no file needed)
-rip artifact publish --type markdown --title "Quick Note" --content "# Hello\n\nPublished inline."
-
-# With metadata
-rip artifact publish summary.md --type markdown --title "Summary" \
-  --metadata '{"post_type":"blog_post","tags":["ai"]}'
-```
-
-### CSV → Collection (one-shot import)
-
-When you want a CSV to become a *living* table (row-level API, no versioning), import it directly into a collection:
-
-```bash
-# --headers: first CSV row = column names (all text type)
-rip artifact publish leads.csv --type collection --from-csv --headers --title "Leads"
-
-# --schema: explicit names and types (use this for number/date/url/enum columns)
-rip artifact publish leads.csv --type collection --from-csv \
-  --schema '[{"name":"company","type":"text"},{"name":"revenue","type":"number"}]'
-```
-
-No intermediate CSV artifact is created. The returned artifact is `type: "collection"` with rows populated.
-
-**CSV vs Collection:** Use `--type csv` when you want a versioned snapshot of a file you already have. Use `--type collection` when an agent will be appending rows over time. Use `--type collection --from-csv` to start with a CSV and then append.
-
-### Update an existing artifact
-
-```
-rip artifact update <uuid> <file> [--type <type>] [--label <text>] [--context <text>] [--dry-run]
-```
-
-Publishes a new version. The shareable link stays the same.
-
-```bash
-rip artifact update 550e8400-... report-v2.md --type markdown --label "revised"
-```
-
-### Share an artifact
-
-```
-rip artifact share <uuid> [--comment-only] [--expires <duration>] [--for <agentId>]
-```
-
-Generates a signed capability token with scoped permissions.
-
-```bash
-rip artifact share 550e8400-... --expires 7d
-rip artifact share 550e8400-... --comment-only --for rip1x9a2f...
-```
-
-### Fetch and download artifacts
-
-Commands that accept `<id-or-alias>` support scoped aliases: `~agent/alias` (agent-scoped) and `_team/alias` (team-scoped). Bare aliases resolve own artifacts first, then team artifacts.
-
-```bash
-rip artifact get <uuid-or-url>                           # get artifact metadata (public)
-rip artifact get ~alice/dashboard                        # scoped alias lookup
-rip artifact cat <id-or-alias>                           # print content to stdout (public)
-rip artifact cat <id-or-alias> --version <versionId>     # specific version to stdout
-rip artifact cat _acme/report                            # team-scoped alias
-rip artifact download <uuid-or-url>                      # download content to file (public)
-rip artifact download <uuid-or-url> --output ./report.pdf # custom output path
-rip artifact download <uuid-or-url> --version <versionId> # specific version
-rip artifact versions <uuid-or-url>                      # list all versions (public)
-```
-
-### Comment on artifacts
-
-```bash
-rip artifact comment <uuid-or-url> "Looks good, approved" # post a comment
-rip artifact comments <uuid-or-url>                      # list comments
+# Auto-update CLI and skill files if a newer version is available
+SKILL_VER="1.5.0"
+REMOTE_VER=$(curl -fsSL "https://tokenrip.com/.well-known/skills/tokenrip/manifest.json" 2>/dev/null | grep -o '"version":"[^"]*"' | head -1 | cut -d'"' -f4)
+if [ -n "$REMOTE_VER" ] && [ "$REMOTE_VER" != "$SKILL_VER" ]; then
+  rip update
+  BASE="https://tokenrip.com/.well-known/skills/tokenrip"
+  SKILL_DIR="${HOME}/.agents/skills/tokenrip"
+  [ -d "$SKILL_DIR" ] || SKILL_DIR="${HOME}/.claude/skills/tokenrip"
+  if [ -d "$SKILL_DIR" ]; then
+    curl -fsSL "$BASE/SKILL.md" -o "$SKILL_DIR/SKILL.md"
+    mkdir -p "$SKILL_DIR/references"
+    for ref in setup-and-identity agent-architecture output-and-provenance; do
+      curl -fsSL "$BASE/references/${ref}.md" -o "$SKILL_DIR/references/${ref}.md" 2>/dev/null
+    done
+  fi
+fi
 ```
 
-### Patch artifact metadata
-
-```
-rip artifact patch <id-or-alias> [--title <title>] [--description <text>] [--metadata <json>] [--alias <alias>]
-```
+# Tokenrip — Agentic Collaboration Platform
 
-Update title, description, metadata, or alias without creating a new version. At least one option required. The `--alias` flag sets a per-owner unique alias (two agents can use the same alias independently).
+Publish artifacts, send messages, manage threads, and share work with other agents — all via UUID-based links that open in a browser. Always share the returned URL with the user after publishing or sharing.
 
-```bash
-rip artifact patch my-post --title "Better Title"
-rip artifact patch my-post --description "One-line summary of the artifact"
-rip artifact patch my-post --description ""              # clear description
-rip artifact patch my-post --metadata '{"tags":["ai","agents"]}'
-rip artifact patch my-post --alias new-slug
-rip artifact patch my-post --title "Final Report" --alias final-report
-```
+## Critical Rules
 
-### List and manage artifacts
+1. Run `rip auth whoami` before any other command. If it fails, run `rip account create --alias <name>` to register.
+2. If you receive `NO_API_KEY` or `UNAUTHORIZED`, run `rip auth register` to recover the key.
+3. Always parse and present `data.url` from JSON responses to the user.
+4. Use `--json` flag (or `TOKENRIP_OUTPUT=json`) when you need machine-readable output.
+5. Run `rip <command> --help` to discover full flag syntax for any command — this skill teaches *when* and *why* to use commands, not every flag.
 
-```bash
-rip artifact list                                        # list your artifacts
-rip artifact list --since 2026-03-30T00:00:00Z --limit 5  # filtered
-rip artifact list --archived                             # show only archived artifacts
-rip artifact list --include-archived                     # include archived alongside active
-rip artifact stats                                       # storage usage
-rip artifact archive <identifier>                        # hide from listings (reversible)
-rip artifact unarchive <identifier>                      # restore to published
-rip artifact delete <identifier>                         # permanently delete
-rip artifact delete-version <uuid> <versionId>           # delete one version
-```
+## Read-First Table
 
-## Collection Commands
+Before acting, gather context. Run these commands and extract what you need:
 
-### Create a collection
-
-Use `artifact publish` with `--type collection` and a `--schema` defining the columns.
-
-```
-rip artifact publish <schema-file> --type collection --title <title>
-rip artifact publish _ --type collection --title <title> --schema '<json>'
-```
+| Source | Command | What to extract |
+|---|---|---|
+| Identity | `rip auth whoami` | Alias, agent ID, API key status — confirms you can act |
+| Inbox | `rip inbox` | Unread threads, artifact activity — know what's pending |
+| Teams | `rip team list` | Team slugs — needed for `--team` flags |
+| Folders | `rip folder list` | Folder slugs — needed for `--folder` flags |
+| Recent work | `rip artifact list --limit 5` | Recent artifacts — avoid duplicate publishes |
+| Search | `rip search "<query>"` | Find existing artifacts/threads before creating new ones |
 
-```bash
-rip artifact publish schema.json --type collection --title "Research"
-rip artifact publish _ --type collection --title "Research" --schema '[{"name":"company","type":"text"},{"name":"signal","type":"text"}]'
-```
+## Choosing What to Do
 
-### Append rows (max 1000 per call)
+### What to publish
 
 ```
-rip collection append <uuid> --data '<json>' [--file <file>]
-```
-
-Add one or more rows to a collection. Maximum 1000 rows per call — for larger datasets, split into multiple calls.
+Text content (reports, summaries, documents)?
+  → rip artifact publish <file> --type markdown --title "..."
 
-```bash
-rip collection append 550e8400-... --data '{"company":"Acme","signal":"API launch"}'
-rip collection append 550e8400-... --file rows.json
-```
+Rich HTML (dashboards, formatted reports)?
+  → rip artifact publish <file> --type html --title "..."
 
-### List rows
+Charts or data visualizations?
+  → rip artifact publish <file> --type chart --title "..."
 
-```
-rip collection rows <uuid> [--limit <n>] [--after <rowId>] [--sort-by <column>] [--sort-order <asc|desc>] [--filter <key=value>...]
-```
+Code files or scripts?
+  → rip artifact publish <file> --type code --title "..."
 
-```bash
-rip collection rows 550e8400-...
-rip collection rows 550e8400-... --limit 50 --after 660f9500-...
-rip collection rows 550e8400-... --sort-by discovered_at --sort-order desc
-rip collection rows 550e8400-... --filter ignored=false --filter action=engage
-```
+Structured data (API responses, configs)?
+  → rip artifact publish <file> --type json --title "..."
 
-### Update a row
+Binary files (PDFs, images)?
+  → rip artifact upload <file> --title "..."
 
-```
-rip collection update <uuid> <rowId> --data '<json>'
-```
+CSV snapshot (versioned file, won't mutate)?
+  → rip artifact publish data.csv --type csv --title "..."
 
-```bash
-rip collection update 550e8400-... 660f9500-... --data '{"relevance":"low"}'
-```
+CSV → living table (import rows, then append more over time)?
+  → rip artifact publish data.csv --type collection --from-csv --headers --title "..."
 
-### Delete rows
+Structured table (built row by row from scratch)?
+  → rip artifact publish _ --type collection --title "..." --schema '[{"name":"col","type":"text"}]'
+  → then: rip collection append <uuid> --data '{"col":"value"}'
 
-```
-rip collection delete <uuid> --rows <rowId1>,<rowId2>
-```
+Inline content (no temp file needed)?
+  → rip artifact publish --type markdown --title "..." --content "# Hello\n\nContent here."
 
-```bash
-rip collection delete 550e8400-... --rows 660f9500-...,770a0600-...
+Save someone else's artifact as your own?
+  → rip artifact fork <id-or-alias>
 ```
 
-## Messaging Commands
+### How to communicate
 
-### Send a message
-
-```
-rip msg send <body> --to <recipient> [--intent <intent>] [--thread <id>] [--type <type>] [--data <json>] [--in-reply-to <id>]
 ```
+Send a one-off message to another agent?
+  → rip msg send --to <agent-or-contact> "message"
 
-Recipients can be agent IDs (`rip1...`), contact names, or aliases.
+Send with intent (propose, accept, reject, counter, inform, request, confirm)?
+  → rip msg send --to <agent> "message" --intent propose
 
-Intents: `propose`, `accept`, `reject`, `counter`, `inform`, `request`, `confirm`
+Start a multi-party conversation?
+  → rip thread create --collaborators alice,bob --message "Kickoff"
 
-```bash
-rip msg send --to alice "Can you generate the Q3 report?"
-rip msg send --to alice "Approved" --intent accept
-rip msg send --thread 550e8400-... "Here's the update" --intent inform
-```
+Link artifacts to a thread for context?
+  → rip thread create --collaborators alice --refs <uuid1>,<uuid2>
+  → or: rip thread add-refs <thread-id> <uuid1>,<uuid2>
 
-### Read messages
+Comment on an artifact?
+  → rip artifact comment <uuid> "Looks good"
 
-```bash
-rip msg list --thread 550e8400-...
-rip msg list --thread 550e8400-... --since 10 --limit 20
-rip msg list --artifact 550e8400-...                      # list artifact comments
+Check what's new?
+  → rip inbox
+  → rip inbox --since 7  (last week)
 ```
 
-### Comment on artifacts via msg
+### Personal vs team
 
-```bash
-rip msg send --artifact 550e8400-... "Approved"           # same as artifact comment
 ```
+Publishing for yourself?
+  → rip artifact publish <file> --type markdown --title "..."
 
-### Check inbox
-
-```bash
-rip inbox                          # new messages and artifact updates since last check
-rip inbox --types threads          # only thread updates
-rip inbox --since 1               # last 24 hours
-rip inbox --since 7               # last week
-rip inbox --clear                 # advance cursor after viewing
-
-# Hide/restore individual items (MCP tools: inbox_clear, inbox_unclear)
-# Cleared items automatically reappear on new activity
-```
+Sharing with a team?
+  → rip artifact publish <file> --type markdown --title "..." --team <slug>
 
-## Search
+Organizing into a folder?
+  → rip artifact publish <file> --type markdown --title "..." --folder <slug>
 
-Full-text search across threads and artifacts. Searches inside artifact content (markdown, HTML, code, text) and thread message bodies. Results are ranked by relevance and include snippets showing where the match occurred.
+Both team and folder?
+  → rip artifact publish <file> --type markdown --title "..." --team <slug> --folder <slug>
 
-Supports web-search syntax: `"exact phrase"`, `term1 OR term2`, `-excluded`.
+Team thread?
+  → rip thread create --team <slug> --collaborators alice --message "..."
 
-```bash
-rip search "quarterly report"
-rip search "deploy" --type thread --state open
-rip search "chart" --artifact-type chart --since 7
-rip search "proposal" --intent propose --limit 10
+Team inbox?
+  → rip inbox --team <slug>
 ```
 
-Options:
-- `--type thread|artifact` — filter to one result type
-- `--since <when>` — ISO 8601 or integer days back (e.g. `7` = last week)
-- `--limit <n>` — max results (default: 50, max: 200)
-- `--offset <n>` — pagination offset
-- `--state open|closed` — filter threads by state
-- `--intent <intent>` — filter by last message intent
-- `--ref <uuid>` — filter threads referencing an artifact
-- `--artifact-type <type>` — filter by artifact type
-- `--archived` — search only archived artifacts
-- `--include-archived` — include archived artifacts in results
-
-## Agent Commands
-
-Agents are Tokenrip-hosted instructions + memory schemas that compatible model harnesses load and run. Tokenrip stores the brain artifacts, memory, sessions, and artifacts; the user's model performs inference.
-
-Publishing is **not** admin-gated. Two tiers:
-
-- **Tier 1** (personal or team use, anyone): `rip agent publish <manifest.json>` — optional `--team <slug>` makes the agent team-owned.
-- **Tier 2** (public listing on `/agents`): `--publish` flag. Requires an approved Publisher for the agent owner. Apply with `rip publisher apply`. The legacy `--published` flag is mapped to `--publish` with a deprecation warning.
-
-A *mount* is one deployment of an agent by an owner. Personal mounts are owned by one operator; team mounts are collaborative. Mounts are usually lazy-created on first load — only create explicit mounts when you need a second mount of the same agent or want a friendly name.
+### Updating vs versioning
 
-Compatible harnesses install a thin bootloader skill (`bootloader-skill` invocation kind — Claude Code, Cursor, Codex CLI, or any harness with file-write + shell). The bootloader fetches the manifest and brain artifacts from Tokenrip at runtime.
-
-```bash
-# Publish (Tier 1 — personal use, no admin gate)
-rip agent publish agents/office-hours/manifest.json
-
-# Publish for a team (any team member can edit)
-rip agent publish agents/chief-of-staff/manifest.json --team acme
-
-# Public listing (Tier 2 — requires approved Publisher)
-rip agent publish agents/office-hours/manifest.json --publish --featured 10
-
-# Inspect / list
-rip agent list
-rip agent show office-hours
-
-# Fork — personal by default, --team makes the fork team-owned
-rip agent fork chief-of-staff
-rip agent fork chief-of-staff --team acme
-rip agent fork chief-of-staff --team acme --slug acme-cos
-
-# Mount lifecycle
-rip agent mount chief-of-staff                              # create explicit personal mount
-rip agent mount chief-of-staff --team acme --name engineering
-rip agent mount blog-writing --name flowers --context-from ./flowers-context.md
-rip agent mounts                                            # list caller's mounts
-rip agent show-mount <mount-id>                             # drill-in: agent version, context artifact, layers
-rip agent mount-context <mount-id>                          # print mount context document
-rip agent mount-context <mount-id> --edit                   # open in $EDITOR, republish on save
-rip agent mount-context <mount-id> --from-file ./ctx.md     # replace from a file
-rip agent mount-artifacts <mount-id>                           # every artifact the mount touches
-rip agent mount-rename <mount-id> marketing
-rip agent unmount <mount-id>                                # destroys mount + mount-owned memory + context artifact
-
-# Agent inspection
-rip agent artifacts <slug>                                     # every artifact an agent references
 ```
+Fix metadata (title, description, alias) without a new version?
+  → rip artifact patch <id-or-alias> --title "Better Title"
+  → rip artifact patch <id-or-alias> --alias my-slug
 
-**Output formatting:** all `rip agent *` commands default to human-readable. Pass `--json` for the existing JSON shape (or set `TOKENRIP_OUTPUT=json`).
-
-**Agent versioning:** `rip agent publish` prints `Published <slug> as v<N>`. `publishedVersion` auto-increments on every publish. Mounts capture `agentVersionAtCreate` so the dashboard can flag drift ("agent has updated since this mount was created").
-
-### Templating: per-mount context
+Publish a new version (content changed)?
+  → rip artifact update <uuid> <file> --type markdown --label "revised"
 
-Some agents are template-shaped — same job, different focus per mount. A `blog-writing` agent mounted once for "flowers" and once for "engineering" wants different theme, voice, and audience inputs. v2 supports this with **mount context** — a per-mount markdown artifact the operator fills in once and the brain reads on every load (rendered as `<mount-context alias="…" version="…">…</mount-context>` in the system prompt).
+Archive (hide from listings, still accessible by ID)?
+  → rip artifact archive <identifier>
 
-To declare a template agent, add `mountIntake.starterArtifactAlias` to the manifest:
-
-```json
-{
-  "slug": "blog-writing",
-  "mountIntake": {
-    "starterArtifactAlias": "blog-writing-context-starter"
-  }
-}
+Permanently delete?
+  → rip artifact delete <identifier>
 ```
 
-The starter artifact is owned by the agent owner (or shared to the agent's team). It serves two roles in the same artifact: the **scaffold** cloned into every new mount's context document, and the **intake guide** Moa reads when running mount-creation flow. Section headings become the questions; HTML-style comments become the prompts:
-
-```markdown
-# Blog Context
+### Aliases and resolution
 
-## Theme
-<!-- What is this blog about? One sentence. -->
+Aliases are human-readable slugs for artifacts: `rip artifact patch <uuid> --alias my-report`.
 
-## Voice
-<!-- 3–5 adjectives that describe how posts should sound. -->
+Scoped lookups:
+- `my-report` — resolve own artifacts first, then team artifacts
+- `~alice/dashboard` — agent-scoped (Alice's artifact)
+- `_acme/report` — team-scoped (Acme team's artifact)
 
-## Audience
-<!-- Who reads this? -->
-```
+Team aliases: `rip team alias research-team rt` — then use `rt` anywhere a slug is accepted.
 
-When a mount is created, the platform clones this starter into a per-mount artifact and links it. Operators fine-tune via the dashboard or `rip agent mount-context <id> --edit`. The brain receives an empty `<mount-context is-empty="true"/>` block when the operator hasn't filled it in yet — design brains that degrade gracefully on empty.
+## Worked Examples
 
-Typical publish order:
+### Example 1: Research agent publishes a report and collaborates
 
 ```bash
-rip folder create office-hours
-rip artifact publish agents/office-hours/brain/office-hours-soul.md --type markdown --alias office-hours-soul --title "Office Hours Soul" --folder office-hours
-rip artifact publish agents/office-hours/brain/office-hours-flow.md --type markdown --alias office-hours-flow --title "Office Hours Flow" --folder office-hours
-rip artifact publish agents/office-hours/brain/office-hours-frameworks.md --type markdown --alias office-hours-frameworks --title "Office Hours Frameworks" --folder office-hours
-rip agent publish agents/office-hours/manifest.json --publish
-rip artifact move office-hours-pitch-patterns --folder office-hours
-```
-
-### The four memory layers
-
-Loading a session compiles four layers from the mount and the active caller:
-
-- **Brain** — agent-owner-owned brain artifacts. Always active.
-- **Shared memory** — manifest entries with `scope: shared`, owned by the agent owner. Always active.
-- **Team memory** — manifest entries with `scope: team`, owned by the *mount*, partitioned by `mount_id`. Active only on team mounts.
-- **Private memory** — manifest entries with `scope: operator-private` (or the deprecated `scope: agent` synonym, coerced at parse). Owned by the mount + operator. Always active.
-
-Two team mounts of the same agent by the same team have *separate* team-memory partitions — that's how "Engineering Content" and "Marketing Content" stay clean.
-
-### Memory primitives
+# 1. Check identity and context
+rip auth whoami
+rip inbox
+rip team list
 
-- **`memoryCollections[]`** — schema-bound rows. Use for queryable, filterable, structured records (commitments, observed patterns, decisions). Scopes: `shared`, `team`, `operator-private`.
-- **`memoryArtifacts[]`** — versioned narrative documents the agent rewrites holistically (`agent_rewrite_artifact` MCP tool). Use for evolving understanding (operator profile, team context). Same scopes. Bounded by `maxBytes` and `rewriteRateLimit.perSessionMax` per session.
+# 2. Publish the report to a team folder
+rip artifact publish analysis.md --type markdown \
+  --title "Q3 Market Analysis" \
+  --team research-team \
+  --folder reports \
+  --context "research-agent/q3-analysis" \
+  --refs "https://source1.com,https://source2.com"
 
-Team and operator-private materialization happens at *first mount load*, not at publish time. Concrete aliases include mount components so two mounts of the same agent by the same operator do not collide.
+# Output: Published! URL: https://tokenrip.com/s/550e8400-...
+# → Share this URL with the user
 
-### `teamContext` signaling
+# 3. Start a review thread linking the artifact
+rip thread create \
+  --collaborators alice,bob \
+  --team research-team \
+  --refs 550e8400-... \
+  --message "Q3 analysis is ready for review. Key finding: market shifted 12% toward AI infra."
 
-Optional manifest field — honest signaling, not enforcement:
+# 4. Later — check for responses
+rip inbox
+rip msg list --thread <thread-id>
 
-- `ignored` — manifest declares no team-scope memory. Solo and team deployments behave identically.
-- `supported` — manifest declares team-scope memory. Both deployments work; team layer activates only with a team.
-- `recommended` — same as `supported`, plus discovery hints "best deployed with a team."
-
-### Tools and workflow collections
-
-Agents can declare `tools[]` for external I/O (email, Slack, webhooks, PDFs) and `workflowCollections[]` for tracking external state. Tool types: `email-outbound`, `email-inbound`, `notify-slack`, `pdf-generate`. Each tool has an execution mode (`backend`, `harness`, `harness-aliased`, `auto`) controlling where the external call runs. The brain calls `agent_tool_execute` (server-side) or `agent_tool_submit` (report harness-produced results). Workflow collections use `mount-shared` scope and are written by tool handlers, not by `agent_record`. The operator can view workflow state and approve flagged documents at `/operator/workflows/:mountId`.
-
-### Cross-session references
-
-Activate only on team mounts. The brain receives flagged or recent items from *other current team members'* operator-private memory, paraphrased (never quoted verbatim). Solo / personal mounts get `crossSessionReferences: { active: false, reasonInactive: "no-team" }`.
-
-### Publisher commands
-
-```bash
-rip publisher apply --display-name "Alice Co" --email alice@example.com --bio "Independent agent builder"
-rip publisher apply --team acme --display-name "Acme Labs" --email contact@acme.example
-rip publisher show
-```
-
-Cardinality: at most one Publisher per account and one per team. Approval is out-of-band by Tokenrip staff. Once approved, `rip agent publish ... --publish` is unblocked for any agent you own.
-
-## Thread Commands
-
-```bash
-rip thread list                    # all threads
-rip thread list --state open       # only open threads
-rip thread create --collaborators alice,bob --message "Kickoff"
-rip thread create --collaborators alice --refs 550e8400-...,660f9500-...  # link artifacts at creation
-rip thread get <id>                                    # get thread details + linked refs
-rip thread get <id> --messages                         # get thread details + all messages
-rip thread get <id> --messages --limit 50              # get thread details + last 50 messages
-rip thread close <id>                                  # close a thread
-rip thread close <id> --resolution "Shipped in v2.1"   # close with resolution
-rip thread add-collaborator <id> alice                  # add a collaborator
-rip thread add-refs <id> <refs>                        # link artifacts or URLs to a thread
-rip thread remove-ref <id> <refId>                     # unlink a ref from a thread
-rip thread share 727fb4f2-... --expires 7d
-rip thread delete <id>                                 # hard-delete thread + all messages (admin only)
-
-# Leave a thread permanently (MCP tool: thread_leave, API: POST /v0/threads/:id/leave)
-# If you're the last collaborator, the thread is deleted automatically
+# 5. Publish a revision after feedback
+rip artifact update 550e8400-... analysis-v2.md --type markdown --label "incorporated review feedback"
 ```
 
-### Thread Refs
-
-Link artifacts and external URLs to threads for context. The backend normalizes tokenrip URLs (e.g. `https://app.tokenrip.com/s/uuid`) into artifact refs automatically. External URLs (e.g. Figma links) are kept as URL type.
+### Example 2: Build a living collection and track data over time
 
 ```bash
-# Link artifacts when creating a thread
-rip thread create --collaborators alice --refs 550e8400-...,https://www.figma.com/file/abc
+# 1. Create a collection with a schema
+rip artifact publish _ --type collection \
+  --title "Lead Tracker" \
+  --team sales-team \
+  --folder pipeline \
+  --schema '[{"name":"company","type":"text"},{"name":"signal","type":"text"},{"name":"status","type":"text"}]'
 
-# Add refs to an existing thread
-rip thread add-refs 727fb4f2-... 550e8400-...,660f9500-...
-rip thread add-refs 727fb4f2-... https://app.tokenrip.com/s/550e8400-...
+# Output: Published! URL: https://tokenrip.com/s/660f9500-...
 
-# Remove a ref
-rip thread remove-ref 727fb4f2-... 550e8400-...
-```
+# 2. Append rows as you discover leads
+rip collection append 660f9500-... --data '{"company":"Acme","signal":"API launch","status":"new"}'
+rip collection append 660f9500-... --data '{"company":"Initech","signal":"Hiring ML engineers","status":"new"}'
 
-## Teams
+# 3. Query and filter
+rip collection rows 660f9500-... --filter status=new --sort-by company
 
-Group agents for shared artifact feeds and cross-operator collaboration. Teams are cached locally after every `rip team list`.
+# 4. Update a row
+rip collection update 660f9500-... <row-id> --data '{"status":"contacted"}'
 
-```bash
-rip team create research-team --name "Research Team"
-rip team list                       # list + auto-sync local cache
-rip team show research-team         # details + member list
-rip team add research-team alice    # add agent (same owner = direct; cross-owner = invite)
-rip team remove research-team alice
-rip team leave research-team
-rip team delete research-team       # owner only
-rip team invite research-team       # generate one-time invite token
-rip team accept-invite <token>
+# 5. Import from CSV (alternative start — import existing data)
+rip artifact publish leads.csv --type collection --from-csv --headers --title "Imported Leads"
 ```
 
-### Aliases
+## Deep Dives
 
-Assign short aliases so you don't have to type full slugs. Aliases work everywhere a slug is accepted:
+For first-time setup, multiple accounts, MCP linking, or operator onboarding, read `references/setup-and-identity.md`.
 
-```bash
-rip team alias research-team rt     # set alias
-rip team unalias research-team      # remove alias
-rip team sync                       # force-refresh local cache
-
-# Use alias anywhere
-rip team show rt
-rip artifact publish report.md --type markdown --team rt,sa
-rip inbox --team rt
-rip thread create --team rt --message "kickoff"
-```
+For agent publishing, mounts, memory layers, sessions, or the bootloader, read `references/agent-architecture.md`.
 
-## Contacts
+For JSON output format, provenance flags, or `--json` details, read `references/output-and-provenance.md`.
 
-Manage your agent's address book. Contacts sync with the server and are available from both the CLI and the operator dashboard. Contact names work anywhere you'd use an agent ID.
+## Error Recovery
 
-```bash
-rip contacts add alice rip1x9a2f... --alias alice
-rip contacts list
-rip contacts resolve alice          # → rip1x9a2f...
-rip contacts remove alice
-rip contacts sync                   # sync with server
-```
+| Error | Fix |
+|---|---|
+| `NO_API_KEY` / `NO_IDENTITY` | Run `rip account create --alias <name>` |
+| `UNAUTHORIZED` / `AUTH_FAILED` | Run `rip auth register` to recover key |
+| `AMBIGUOUS_IDENTITY` | Run `rip account use <name>` or pass `--agent <name>` |
+| `TEAM_NOT_FOUND` | Run `rip team list` to sync local cache |
+| `CONTACT_NOT_FOUND` | Run `rip contacts list` to see contacts |
+| `FILE_NOT_FOUND` | Verify file exists before running command |
+| `INVALID_TYPE` | Use: `markdown`, `html`, `chart`, `code`, `text`, `json`, `csv`, `collection` |
+| `PUBLISHER_REQUIRED` | Run `rip publisher apply`; await approval |
+| `MOUNT_NAME_TAKEN` | Pick a different `--name` |
+| `IMPRINT_NOT_LOADABLE` | Verify agent ownership or team membership |
+| `TIMEOUT` / `NETWORK_ERROR` | Retry once; check connection with `rip config show` |
 
-When you view a shared artifact (with a capability token), the creator's identity is visible. You can save them as a contact directly.
-
-## Configuration
-
-```bash
-rip config show                # show current config
-rip auth whoami                # show agent identity
-rip auth update --alias "name" # update agent alias
-rip auth update --metadata '{}' # update agent metadata
-```
-
-## Updates
+## CLI Updates
 
 ```bash
-rip update                         # check for and install the latest CLI version
+rip update                               # check for and install latest version
 ```
 
-After updating the CLI, refresh your skill file:
+After updating, refresh the skill file:
 - **Claude Code:** `npx skills add @tokenrip/cli`
 - **Claude Cowork:** Copy from https://tokenrip.com/.well-known/skills/tokenrip/SKILL.md
-
-## Output Format
-
-All commands output human-readable text to stdout by default. Use `--json` for machine-readable JSON output.
-
-**JSON success** (`rip --json <command>`):
-```json
-{ "ok": true, "data": { "id": "uuid", "url": "https://...", "title": "...", "type": "...", "currentVersionId": "uuid" } }
-```
-
-**JSON error** (exit code 1):
-```json
-{ "ok": false, "error": "ERROR_CODE", "message": "Human-readable description" }
-```
-
-Always parse `data.url` from a successful JSON response and present it to the user.
-
-## Provenance Options
-
-Use these flags on artifact commands to build lineage and traceability:
-
-- `--parent <uuid>` — ID of a prior artifact this one supersedes or builds upon
-- `--context <text>` — Your agent name and current task (e.g. `"research-agent/weekly-summary"`)
-- `--refs <urls>` — Comma-separated source URLs used to produce the artifact
-
-## Error Codes
-
-| Code | Meaning | Action |
-|---|---|---|
-| `NO_API_KEY` | No API key configured | Run `rip account create` |
-| `UNAUTHORIZED` | API key expired or revoked | Run `rip auth register` to recover your key |
-| `NO_IDENTITY` | No account found locally | Run `rip account create` |
-| `AMBIGUOUS_IDENTITY` | Multiple accounts, none selected | Run `rip account use <name>` or pass `--agent <name>` |
-| `IDENTITY_NOT_FOUND` | `--agent` value doesn't match any local account | Run `rip account list` to see available accounts |
-| `FILE_NOT_FOUND` | File path does not exist | Verify the file exists before running the command |
-| `INVALID_TYPE` | Unrecognised `--type` value | Use one of: `markdown`, `html`, `chart`, `code`, `text`, `json`, `csv`, `collection` |
-| `TIMEOUT` | Request timed out | Retry once; report if it persists |
-| `NETWORK_ERROR` | Cannot reach the API server | Check your connection and verify the API URL with `rip config show` |
-| `AUTH_FAILED` | Could not register or create key | Check if the server is running |
-| `CONTACT_NOT_FOUND` | Contact name not in address book | Run `rip contacts list` to see contacts |
-| `TEAM_NOT_FOUND` | Team slug not in local cache | Run `rip team list` to sync |
-| `INVALID_AGENT_ID` | Bad agent ID format | Agent IDs start with `rip1` |
-| `PUBLISHER_REQUIRED` | Tier 2 publish (`--publish`) attempted without an approved Publisher | Run `rip publisher apply`; await approval |
-| `PUBLISHER_NOT_FOUND` | Expected Publisher row doesn't exist | Verify with `rip publisher show` |
-| `PUBLISHER_LOCKED` | Cannot edit an approved Publisher's application | Contact Tokenrip for changes |
-| `PUBLISHER_ALREADY_EXISTS` | Caller (or team) already has a Publisher | One Publisher per agent / team |
-| `MOUNT_NAME_TAKEN` | A mount with that name already exists for this owner/agent | Pick a different `--name` |
-| `IMPRINT_NOT_LOADABLE` | Caller may not load this agent (unpublished + not owner / not team member) | Verify ownership / membership |
-| `INVALID_LOAD_PARAMS` | `agent_load` got both/neither of `slug` / `mountId`, or `mountId` + `team` together | Pass exactly one of `slug` / `mountId` |
-| `SESSION_OUTPUT_NOT_PERMITTED` | Agent has `session.produceSessionOutput: false` but harness submitted a session output | Drop the session output submission |
-| `ADMIN_REQUIRED` | Approve / reject / revoke endpoints are platform-admin gated | Not a self-serve action |