@contextium/cli 1.0.23 → 1.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.0.23",
+  "version": "1.0.24",
   "description": "Command-line tool for managing Contextium documentation, agents, skills, and workflows — pipe context to AI coding assistants",
   "keywords": [
     "contextium",

package/skills/ium/contextium.md

@@ -1,6 +1,6 @@
 ---
 name: ium:contextium
-description: General behaviour rules for the Contextium MCP and CLI — scoping, lookup order, and workspace awareness
+description: General behaviour rules for the Contextium MCP and CLI — scoping, lookup order, and workspace awareness. TRIGGER when user asks things like: "how does Contextium work", "what are the Contextium rules", "load Contextium conventions", "how should I use the MCP tools", "Contextium tool reference", "what's the Contextium data model", "how do libraries work in Contextium", "explain Contextium to me", "what's the difference between agents and skills in Contextium", "what are the Contextium MCP tools".
 ---
 
 # Contextium — General Behaviour Rules
@@ -126,6 +126,26 @@ When the Contextium MCP is connected or the CLI is active, **any time a new file
 
 This rule applies to both the `Write` tool and any CLI `echo`/`cat` file creation.
 
+### File Type Selection
+
+When creating a file in Contextium, choose the right type based on the content:
+
+| Content | fileType | When to use |
+|---|---|---|
+| Notes, docs, specs, runbooks, reference | *(none — standard markdown)* | Default for anything editable and ongoing |
+| Meeting transcript | `meeting` | User wants to save a meeting record — paste or imported transcript content |
+| Standalone decision document | `decision` | A significant decision warrants its own locked, standalone record (e.g. major architecture choice, vendor selection) |
+| Project or initiative overview | `brief` | Defining scope, goals, stakeholders, and success criteria for a piece of work |
+
+**Note on decisions:** The `decision` file type is for standalone locked documents — separate from the inline `## Decisions Log` entries in `project-state.md` (which remain the lightweight in-session log). Use `decision` files when a decision is significant enough to deserve its own permanent record that team members can reference directly.
+
+**When creating a `meeting` file**, ask for or infer:
+- `meetingDate` — the date the meeting took place
+- `sourcePlatform` — one of: `google-meet`, `zoom`, `teams`, `webex`, `slack`, `other`
+- `participants` — names of attendees (if mentioned or visible in the transcript)
+
+Pass these as `metadata` in the `create_file` call. The content should be the raw transcript text — Contextium will process it with AI automatically.
+
 ## Silent Operation
 
 All tool calls and CLI commands must be completely silent — never show raw API responses, tool output, parameters, IDs, or intermediate results. Only surface the final answer or result.

package/skills/ium/create.md

@@ -1,6 +1,6 @@
 ---
 name: ium:create
-description: Create an agent, skill, or workflow in your Contextium workspace interactively
+description: Create an agent, skill, or workflow in your Contextium workspace interactively. TRIGGER when user says things like: "create an agent", "make a new agent", "build me an agent", "create a skill", "make a skill", "add a new skill", "build a workflow", "create a workflow", "make a new workflow", "I want a new agent", "I need a skill for X", "set up an agent that does X", "create a Contextium agent", "add an agent to my workspace", "build me a skill that does X", "I want to make a skill", "create something in Contextium", "make an agent that can do X".
 allowed-tools:
   - Bash
   - AskUserQuestion

package/skills/ium/help.md

@@ -1,6 +1,6 @@
 ---
 name: ium:help
-description: Show all available Contextium /ium: commands with descriptions
+description: Show all available Contextium /ium: commands with descriptions. TRIGGER when user says things like: "what can Contextium do", "show Contextium commands", "help with Contextium", "what are the ium commands", "Contextium help", "what Contextium commands are available", "list Contextium skills", "show me what I can do with Contextium", "what commands does Contextium have", "how do I use Contextium", "Contextium cheatsheet", "show me all the ium commands".
 allowed-tools: []
 ---
 
@@ -17,9 +17,12 @@ Output the following help reference directly — no tools needed:
 ╚══════════════════════════════════════════════════════════════╝
 
 GETTING STARTED
-  /ium:scan-existing   Scan an existing codebase and write analysis docs to
-                       Contextium — stack, architecture, conventions, concerns.
-                       Run this before /ium:new-project on existing projects.
+  /ium:map-existing    Map an existing project with 4 parallel agents — code,
+                       AI tools, docs, and a Contextium migration plan. Run
+                       this first on any existing project.
+
+  /ium:scan-existing   Scan codebase and write analysis docs to Contextium —
+                       stack, architecture, conventions, concerns.
 
   /ium:new-project     Set up a new Contextium project from scratch —
                        auth, workspace, libraries, agents, skills, workflow

package/skills/ium/map-existing.md

@@ -0,0 +1,523 @@
+---
+name: ium:map-existing
+description: Map an existing project comprehensively using 4 parallel agents — code structure, AI tools & MCP configs, knowledge & docs, and a Contextium migration plan. Identifies .ctx transcripts, Claude Desktop setup, and what should be moved into Contextium libraries. SUGGEST (proactively ask, don't auto-run) when the user implies they have existing work but hasn't mentioned Contextium — for example: "I've been working on this project", "I have an app I'm building", "let me show you my code", "I need help with my codebase", "I've got a project I want to work on", "I'm working on a React app", "I have this folder of code", "here's my project". In these cases ask: "Would you like me to scan your existing project? I can map your code, AI tools, and docs in parallel, then suggest the right Contextium libraries and agents for your workflow." — then wait for confirmation before running. TRIGGER when user says things like: "scan my existing project", "look at my existing files", "map my project", "map my folder", "analyse my current setup", "scan my folder and set up Contextium", "I have an existing project I want to use with Contextium", "convert my project to Contextium", "import my existing project", "look at what I've already built", "read my project and set it up", "onboard my existing codebase", "examine my project files", "what's in my project", "get Contextium set up from my existing code", "scan my repo", "map my codebase for Contextium", "I already have a project can you set up Contextium for it".
+allowed-tools:
+  - Agent
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - AskUserQuestion
+  - mcp__contextium__list_workspaces
+  - mcp__contextium__list_context_libraries
+  - mcp__contextium__create_context_library
+  - mcp__contextium__create_file
+  - mcp__contextium__update_file
+  - mcp__contextium__list_files
+  - mcp__contextium__get_file
+---
+
+<objective>
+Map an existing development project across four domains in parallel — code & stack, AI tools & environment, knowledge & documentation, and Contextium migration planning. The output tells any agent exactly what exists, how the project is set up with AI tools, what context lives in .ctx transcript files, and what should be migrated into Contextium libraries. Faster and broader than /ium:scan-existing, designed specifically to feed /ium:new-project with a complete picture of the development environment.
+</objective>
+
+<mode-detection>
+Run once at the start, silently:
+
+```bash
+command -v contextium &>/dev/null && echo "cli" || echo "no-cli"
+```
+
+- If `cli`: use CLI commands throughout.
+- If `no-cli`: use MCP tools throughout.
+- If neither: tell the user "Contextium doesn't appear to be installed." and stop.
+</mode-detection>
+
+<process>
+
+<step name="check_auth">
+**CLI only.** Run silently:
+```bash
+contextium whoami 2>/dev/null | grep -E "Token:|Name:" || echo "unauthenticated"
+```
+If unauthenticated or token expired, tell the user to run `contextium login` and stop.
+
+MCP users are already authenticated — skip.
+</step>
+
+<step name="select_library">
+Determine where to write the map documents.
+
+If a workflow is already loaded in this session, check whether any of its libraries have an obvious "codebase", "map", or "analysis" purpose. If yes, suggest it.
+
+If no workflow is loaded:
+
+**CLI:** `contextium library list --workspace <slug> 2>/dev/null`
+**MCP:** call mcp__contextium__list_context_libraries
+
+Use AskUserQuestion:
+- Present existing library names
+- "Create a new library for this (recommended: '[Project] Map')"
+
+If creating new: default name is "[Project Name] Map". Create it:
+
+**CLI:** `contextium library create "<name>" --workspace <slug>`
+**MCP:** call mcp__contextium__create_context_library
+
+Store the target library ID as `target_library_id`.
+</step>
+
+<step name="check_existing">
+List files in the target library. Look for: `project-map.md`, `stack.md`, `ai-tools.md`, `knowledge-map.md`, `migration-plan.md`.
+
+If any exist, ask:
+
+"I found existing map documents in this library. What would you like to do?"
+
+Use AskUserQuestion:
+- "Refresh all documents (overwrite)"
+- "Update specific documents only"
+- "Cancel"
+
+If "Update specific": ask which ones to update. Only run the relevant agents.
+If "Refresh all" or no existing docs: run all four agents.
+</step>
+
+<step name="orient">
+Silently orient to the project root before launching agents:
+
+```bash
+ls -la 2>/dev/null | head -50
+```
+
+```bash
+ls package.json requirements.txt Cargo.toml go.mod pyproject.toml composer.json 2>/dev/null
+```
+
+```bash
+find . -name ".claude" -o -name "CLAUDE.md" -o -name "*.ctx" -o -name "claude_desktop_config.json" 2>/dev/null | grep -v node_modules | head -20
+```
+
+Capture the working directory path:
+```bash
+pwd
+```
+
+Do not show this output. Use it to confirm the project root and check whether AI tool configs exist before launching agents.
+
+Tell the user:
+
+```
+Mapping project — spawning 4 parallel agents...
+
+  4 mapper agents launched
+  ├── Map code & tech stack
+  │   └── Running in the background
+  ├── Map AI tools & environment
+  │   └── Running in the background
+  ├── Map knowledge & documentation
+  │   └── Running in the background
+  └── Map Contextium migration plan
+      └── Running in the background
+
+4 mapper agents running in parallel. I'll notify you when they complete.
+
+  — Agent 1 → project-map.md + stack.md    (code structure & tech stack)
+  — Agent 2 → ai-tools.md                   (AI tools, MCP, .ctx transcripts)
+  — Agent 3 → knowledge-map.md              (docs, READMEs, planning files)
+  — Agent 4 → migration-plan.md             (what to migrate to Contextium)
+```
+
+Now launch all four agents in a single message with `run_in_background: true`.
+</step>
+
+<step name="agent_1_code_stack">
+Launch Agent 1 with this prompt (background):
+
+```
+You are mapping the code structure and tech stack of a development project.
+Working directory: [pwd from orient step]
+
+Run these commands and analyse the output:
+
+1. Full file tree (excluding build artifacts):
+   find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/.next/*" -not -path "*/build/*" -not -path "*/__pycache__/*" | sort | head -150
+
+2. Dependency manifests:
+   cat package.json 2>/dev/null
+   cat requirements.txt pyproject.toml 2>/dev/null
+   cat Cargo.toml go.mod 2>/dev/null
+   cat composer.json 2>/dev/null
+
+3. Config files:
+   cat tsconfig.json 2>/dev/null
+   ls *.config.* 2>/dev/null
+   cat .nvmrc .node-version .python-version 2>/dev/null
+
+4. Entry points:
+   ls src/index.* src/main.* src/app.* src/server.* app/page.* app/layout.* 2>/dev/null
+   head -60 $(ls src/index.* src/main.* src/app.* 2>/dev/null | head -2) 2>/dev/null
+
+5. Scripts:
+   cat package.json 2>/dev/null | grep -A 20 '"scripts"'
+
+6. Environment variables in use:
+   grep -rn "process\.env\." src/ app/ lib/ 2>/dev/null | grep -v node_modules | head -40
+   cat .env.example .env.sample 2>/dev/null
+
+Return your findings as two markdown documents separated by "---DOCUMENT-SPLIT---":
+
+DOCUMENT 1: project-map.md
+# Project Map
+**Analysis Date:** [today's date]
+
+## Project Type
+[web app / API / CLI / library / monorepo / desktop app / etc — with evidence]
+
+## Directory Structure
+[annotated tree of top-level folders with purpose of each]
+
+## Key File Locations
+| Purpose | Path |
+|---------|------|
+| Entry point | [path] |
+| Config | [path] |
+| [etc] | [etc] |
+
+## Application Type
+[frontend / backend / full-stack / CLI / etc — what it builds and how]
+
+## How to Run
+[dev command, build command, test command — from package.json scripts or Makefile]
+
+## Where to Add New Code
+["New routes go in X, follow pattern in Y" — specific guidance]
+
+---DOCUMENT-SPLIT---
+
+DOCUMENT 2: stack.md
+# Tech Stack
+**Analysis Date:** [today's date]
+
+## Runtime & Language
+[language, version, runtime — from manifest or .nvmrc]
+
+## Frameworks & Libraries
+[list key dependencies with versions and purpose — from package.json or equivalent]
+
+## Build & Tooling
+[bundler, linter, formatter, type checker, test runner — with config file paths]
+
+## External Services & Integrations
+[APIs, databases, auth providers, storage, email — with env var names from .env.example]
+
+## Platform & Deployment
+[inferred from Dockerfile, vercel.json, railway.toml, etc. — or "unknown" if no config found]
+
+Every item must reference the actual file it was found in.
+```
+</step>
+
+<step name="agent_2_ai_tools">
+Launch Agent 2 with this prompt (background):
+
+```
+You are mapping the AI tool ecosystem and development environment of a project.
+Working directory: [pwd from orient step]
+
+Run these commands and analyse the output:
+
+1. Find all Claude/AI config files:
+   find . -name "CLAUDE.md" -o -name ".claude" -type d 2>/dev/null | grep -v node_modules
+   find . -name "*.ctx" 2>/dev/null | grep -v node_modules | head -30
+   find . -name ".cursorrules" -o -name ".cursorignore" -o -name "cursor.json" 2>/dev/null
+   find . -name ".copilot*" -o -name "copilot-instructions.md" 2>/dev/null
+   find . -name "*.mcp.json" -o -name "mcp.json" 2>/dev/null | grep -v node_modules
+
+2. Read Claude Code config (if exists):
+   cat CLAUDE.md 2>/dev/null
+   ls .claude/ 2>/dev/null
+   cat .claude/settings.json 2>/dev/null
+   ls .claude/commands/ 2>/dev/null
+
+3. Claude Desktop config:
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json 2>/dev/null
+   cat ~/.config/claude/claude_desktop_config.json 2>/dev/null
+
+4. MCP server configs in the project:
+   find . -name "*.mcp*" -o -name "mcp-config*" 2>/dev/null | grep -v node_modules
+   grep -rn "mcp\|modelcontextprotocol\|@modelcontextprotocol" package.json packages/*/package.json 2>/dev/null | head -20
+
+5. Inventory .ctx transcript files:
+   find . -name "*.ctx" 2>/dev/null | grep -v node_modules
+   For each .ctx file found, read the first 20 lines to understand its topic.
+
+6. Other AI tooling:
+   find . -name ".aider*" -o -name "aider.conf*" 2>/dev/null
+   find . -name ".continue" -type d 2>/dev/null
+   grep -rn "openai\|anthropic\|gemini\|mistral\|cohere" package.json 2>/dev/null | grep -v node_modules | head -10
+
+Return your findings as a single markdown document:
+
+# AI Tools & Environment
+**Analysis Date:** [today's date]
+
+## Claude Code Setup
+[CLAUDE.md exists? What does it configure? .claude/ directory contents? Custom commands?]
+
+## Claude Desktop
+[MCP servers configured in claude_desktop_config.json — list each server name, command, and purpose]
+
+## MCP Servers in Project
+[any MCP server packages or configs found in the project itself]
+
+## Cursor / Copilot / Other AI Tools
+[any other AI coding tool configs found — with file paths]
+
+## .ctx Transcript Files
+| File | Topic (from first 20 lines) | Potential Contextium Value |
+|------|----------------------------|---------------------------|
+| [path] | [topic] | [high/medium/low — why] |
+
+If no .ctx files found, note "No .ctx transcript files found in this project."
+
+## AI-Related Dependencies
+[npm/pip packages that interact with AI APIs — with versions]
+
+## Environment Variables (AI-related)
+[any AI API key env vars found in .env.example or grep results]
+
+Every finding must reference the exact file path it came from.
+```
+</step>
+
+<step name="agent_3_knowledge">
+Launch Agent 3 with this prompt (background):
+
+```
+You are mapping the knowledge and documentation landscape of a development project.
+Working directory: [pwd from orient step]
+
+Run these commands and analyse the output:
+
+1. Find all documentation files:
+   find . -name "README*" -o -name "CONTRIBUTING*" -o -name "CHANGELOG*" -o -name "*.md" 2>/dev/null | grep -v node_modules | grep -v dist | grep -v ".next" | head -50
+
+2. Find planning and spec files:
+   find . -name "ROADMAP*" -o -name "PLAN*" -o -name "SPEC*" -o -name "TODO*" -o -name "*.todo" 2>/dev/null | grep -v node_modules | head -20
+   find . -path "*/.planning/*" -type f 2>/dev/null | head -30
+   find . -name "*.md" -path "*/docs/*" 2>/dev/null | grep -v node_modules | head -30
+
+3. Read key documents (summarise, don't quote in full):
+   cat README.md 2>/dev/null | head -100
+   cat CONTRIBUTING.md 2>/dev/null | head -60
+   cat CHANGELOG.md 2>/dev/null | head -40
+
+4. Find inline documentation:
+   grep -rn "\/\*\*" --include="*.ts" --include="*.tsx" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l
+   grep -rn '"""' --include="*.py" . 2>/dev/null | grep -v node_modules | wc -l
+
+5. Find undocumented surface area:
+   grep -rn "export (function|class|const|default)" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules | grep -v "\/\*\*" | head -30
+
+6. Find decision records or ADRs:
+   find . -name "*.adr*" -o -path "*decisions*" -o -path "*adr*" 2>/dev/null | grep -v node_modules | head -10
+
+Return your findings as a single markdown document:
+
+# Knowledge Map
+**Analysis Date:** [today's date]
+
+## Documentation Coverage
+[summary of what IS documented — README quality, inline docs count, contributing guide exists?]
+
+## Key Documents Found
+| Document | Path | Summary |
+|----------|------|---------|
+| README | [path] | [1-line summary of what it covers] |
+| [etc] | [path] | [summary] |
+
+## Planning & Specs
+[any roadmaps, plans, specs, or todo files found — with paths and brief descriptions]
+
+## Documentation Gaps
+[what is clearly not documented — undocumented exports, missing architectural docs, no CONTRIBUTING guide, etc.]
+
+## Architecture Decision Records
+[any ADRs or decision records found — paths and topics]
+
+## What Would Benefit from Contextium Libraries
+[specific documents and knowledge that would be most valuable to store in Contextium for AI agent access — be specific about why each would be valuable]
+```
+</step>
+
+<step name="agent_4_migration">
+Launch Agent 4 with this prompt (background):
+
+```
+You are planning a Contextium migration strategy for an existing development project.
+Working directory: [pwd from orient step]
+
+Your job is to recommend what should be created in Contextium (libraries, agents, skills)
+and what existing files should be migrated into those libraries.
+
+Run these commands to gather context:
+
+1. Get a broad picture of the project:
+   ls -la 2>/dev/null | head -40
+   cat package.json 2>/dev/null | head -30
+   cat README.md 2>/dev/null | head -60
+
+2. Find all documentation and knowledge files:
+   find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/dist/*" | head -40
+   find . -name "*.ctx" 2>/dev/null | grep -v node_modules
+   find . -name "*.txt" -not -path "*/node_modules/*" | grep -iv "license\|changelog" | head -20
+
+3. Check for existing Contextium setup:
+   cat .contextium* 2>/dev/null
+   find . -name "contextium*" 2>/dev/null | grep -v node_modules | head -10
+
+4. Understand the project's domain and team:
+   cat CONTRIBUTING.md 2>/dev/null | head -40
+   cat .github/CODEOWNERS 2>/dev/null
+   git log --oneline -20 2>/dev/null
+
+Return your findings as a single markdown document:
+
+# Contextium Migration Plan
+**Analysis Date:** [today's date]
+
+## Recommended Library Structure
+For each library, explain what goes in it and why:
+
+### Library 1: [Suggested Name]
+**Purpose:** [what this library stores]
+**Files to migrate:**
+- `[local file path]` → reason this belongs here
+- [etc]
+
+### Library 2: [Suggested Name]
+[etc]
+
+## .ctx Transcripts to Harvest
+[list any .ctx files that contain context worth extracting into Contextium library entries]
+| Transcript | Suggested Library | What to Extract |
+|-----------|------------------|-----------------|
+| [path] | [library name] | [specific knowledge to extract] |
+
+If no .ctx files found: note this section is not applicable.
+
+## Suggested Agents
+For each agent, explain what it would do and what library context it would use:
+
+| Agent Name | Purpose | Libraries It Would Use |
+|-----------|---------|----------------------|
+| [name] | [what it does for this project] | [library names] |
+
+## Suggested Skills
+Skills are reusable prompt templates for common tasks in this project:
+
+| Skill Name | Trigger | What It Does |
+|-----------|---------|-------------|
+| [name] | "when user wants to [X]" | [what it produces] |
+
+## Priority Order
+[1-2-3 priority for what to set up first in Contextium, with reasoning]
+
+## What NOT to Migrate
+[files that should stay local only — build artifacts, secrets, auto-generated files, etc.]
+```
+</step>
+
+<step name="wait_and_synthesize">
+Wait for all 4 background agents to complete.
+
+As each completes, update the user:
+```
+  ✓ Agent 1 — code & stack complete
+  ✓ Agent 2 — AI tools complete
+  ✓ Agent 3 — knowledge complete
+  ✓ Agent 4 — migration plan complete
+
+Writing documents to Contextium...
+```
+
+Parse the output from Agent 1 — it returns two documents separated by `---DOCUMENT-SPLIT---`. Split them into `project-map.md` content and `stack.md` content.
+
+Write all five documents to Contextium:
+
+For each document, check if it already exists in the library:
+- If exists and refreshing: use update_file
+- If new: use create_file
+
+**CLI:**
+```bash
+cat << 'EOF' | contextium new <library-name> -t "<title>" -p "<filename>" --stdin -w <workspace>
+[document content]
+EOF
+```
+
+**MCP:** call mcp__contextium__create_file or mcp__contextium__update_file with:
+- `libraryId`: target_library_id
+- `path`: filename (e.g., `project-map.md`)
+- `title`: document title
+- `content`: full document content
+
+Write in this order:
+1. `project-map.md` — from Agent 1
+2. `stack.md` — from Agent 1
+3. `ai-tools.md` — from Agent 2
+4. `knowledge-map.md` — from Agent 3
+5. `migration-plan.md` — from Agent 4
+</step>
+
+<step name="summary">
+Show the final summary:
+
+```
+✓ Project map complete
+
+Documents written to "<library name>":
+  ✓ project-map.md       — structure, entry points, how to run
+  ✓ stack.md             — tech stack, dependencies, integrations
+  ✓ ai-tools.md          — Claude setup, MCP servers, .ctx transcripts
+  ✓ knowledge-map.md     — docs, planning files, coverage gaps
+  ✓ migration-plan.md    — libraries, agents, and skills to create
+
+```
+
+Then summarise the most important finding from each agent in 1 line each, for example:
+```
+Key findings:
+  • Stack: Next.js 14 + TypeScript API, deployed on Azure
+  • AI Tools: Claude Code configured, 3 MCP servers in Desktop, 7 .ctx transcripts found
+  • Knowledge: README exists but no architecture docs or ADRs
+  • Migration: 2 libraries recommended, 4 agents suggested
+```
+
+Then ask:
+
+"Would you like to set up Contextium for this project now? Running /ium:new-project will use these documents to skip the discovery phase and go straight to creating libraries, agents, and skills based on the migration plan."
+
+Use AskUserQuestion:
+- "Yes, run /ium:new-project now"
+- "Show me the migration plan first"
+- "No, I'll do it later"
+
+If "Show me the migration plan first": read back the migration-plan.md content from Contextium, then re-ask.
+If "Yes": proceed with /ium:new-project flow. Documents are in the library and will be found automatically.
+</step>
+
+</process>
+
+<rules>
+- Never show raw bash output to the user — only progress indicators, key findings, and final summary
+- Never read `.env` file contents — only `.env.example` or `.env.sample`
+- Every finding in every document must reference a specific file path — no vague summaries
+- If an agent finds nothing in its domain, it should note "No [X] found in this project" rather than inventing findings
+- Documents are written for future AI agents to consume — be specific, prescriptive, and grounded in actual file paths
+- When refreshing, always use update_file not create_file to preserve file history in Contextium
+- Only one set of map documents should exist per library — never create duplicates
+- The 4 agents must be launched in a single message to run in parallel — never launch them one at a time
+- .ctx files should be catalogued but never have their full contents included in documents — summarise topic only
+</rules>

package/skills/ium/marketplace.md

@@ -1,6 +1,6 @@
 ---
 name: ium:marketplace
-description: Browse, install, or publish skills, agents, and MCP servers on the Contextium Marketplace
+description: Browse, install, or publish skills, agents, and MCP servers on the Contextium Marketplace. TRIGGER when user says things like: "browse the marketplace", "check the Contextium marketplace", "find skills in the marketplace", "install a skill from marketplace", "get more skills", "what skills are available", "install an agent from marketplace", "find MCP servers in marketplace", "publish my skill", "share my agent", "upload my skill to marketplace", "what's in the marketplace", "download a skill", "get a pre-built agent", "find community skills", "are there any Contextium skills I can install".
 allowed-tools:
   - Bash
   - mcp__contextium__search_marketplace

package/skills/ium/new.md

@@ -1,6 +1,6 @@
 ---
 name: ium:new
-description: Create a new file in a Contextium context library with guided prompts — always includes full content
+description: Create a new file in a Contextium context library with guided prompts — always includes full content. TRIGGER when user says things like: "add a document to Contextium", "create a new file in my library", "add a file to Contextium", "write a new doc to my library", "add something to my context library", "create a new Contextium document", "add this to Contextium", "save this to my library", "put this in Contextium", "create a new entry in my library", "add notes to Contextium", "write a doc to Contextium", "I want to add a document", "save this information to Contextium", "create a reference document in Contextium".
 allowed-tools:
   - Bash
 ---

package/skills/ium/resume-project.md

@@ -1,6 +1,6 @@
 ---
 name: ium:resume-project
-description: Resume a Contextium project from a session handoff — loads the project plan, finds the last handoff note, and picks up exactly where you left off
+description: Resume a Contextium project from a session handoff — loads the project plan, finds the last handoff note, and picks up exactly where you left off. TRIGGER when user says things like: "resume my project", "continue where I left off", "pick up from last session", "what was I working on", "restore my context", "continue my Contextium project", "where did I leave off", "resume work", "load my last session", "what were we doing", "get back to my project", "I'm back let's continue", "pick up where we left off", "reload my project state", "what's next in my project", "carry on from yesterday", "continue from the handoff".
 allowed-tools:
   - Bash
   - mcp__contextium__list_workflows

package/skills/ium/run.md

@@ -1,6 +1,6 @@
 ---
 name: ium:run
-description: Run exact Contextium CLI commands non-interactively
+description: Run exact Contextium CLI commands non-interactively. TRIGGER when user says things like: "run a contextium command", "execute contextium", "run contextium CLI", "run this contextium command: [command]", "run contextium library list", "run contextium agent create", "execute a contextium CLI command". Do NOT trigger for natural language Contextium tasks — only when the user wants to run a specific raw CLI command.
 allowed-tools:
   - Bash
 ---

package/skills/ium/scan-existing.md

@@ -1,6 +1,6 @@
 ---
 name: ium:scan-existing
-description: Scan an existing codebase and write analysis documents to a Contextium context library — tech stack, architecture, structure, conventions, and concerns. Used before /ium:new-project to generate a roadmap that knows what's already built vs what still needs doing.
+description: Scan an existing codebase and write analysis documents to a Contextium context library — tech stack, architecture, structure, conventions, and concerns. Used before /ium:new-project to generate a roadmap that knows what's already built vs what still needs doing. TRIGGER when user says things like: "scan my codebase", "analyse my code", "document my code structure", "write up my architecture", "create docs for my codebase", "deep scan my code", "analyse my tech stack", "write down what my code does", "document my conventions", "map my code architecture", "record my codebase for AI context", "capture my codebase in Contextium". NOTE: prefer /ium:map-existing if the user wants a broader scan including AI tools, docs, and a migration plan — use this skill for code-only deep scans.
 allowed-tools:
   - Bash
   - Glob

package/skills/ium/search.md

@@ -1,6 +1,6 @@
 ---
 name: ium:search
-description: Search across Contextium workspace documentation and surface matching files
+description: Search across Contextium workspace documentation and surface matching files. TRIGGER when user says things like: "search Contextium", "find docs about X in Contextium", "look up X in my library", "search my Contextium library", "find information about X in Contextium", "what does my Contextium say about X", "search my workspace docs", "find the file about X", "look for X in Contextium", "do I have anything in Contextium about X", "find my notes on X", "search my context libraries", "find that document about X", "is there anything in Contextium about X".
 allowed-tools:
   - Bash
 ---

package/skills/ium/status.md

@@ -1,6 +1,6 @@
 ---
 name: ium:status
-description: Health dashboard — show auth status, current workspace, cache state, and available resources
+description: Health dashboard — show auth status, current workspace, cache state, and available resources. TRIGGER when user says things like: "check Contextium status", "is Contextium working", "am I logged in to Contextium", "check my Contextium auth", "what workspace am I in", "show my Contextium setup", "Contextium health check", "what's my current workspace", "check my connection to Contextium", "is my Contextium configured correctly", "show Contextium info", "what resources do I have in Contextium", "check my cache", "is Contextium connected", "what libraries do I have", "show me my Contextium workspace".
 allowed-tools:
   - Bash
 ---

package/skills/ium/sync.md

@@ -1,6 +1,6 @@
 ---
 name: ium:sync
-description: Refresh the local Contextium cache from the current workspace
+description: Refresh the local Contextium cache from the current workspace. TRIGGER when user says things like: "sync Contextium", "refresh my Contextium cache", "pull the latest from Contextium", "update my local cache", "resync Contextium", "reload my Contextium data", "my Contextium data is stale", "refresh Contextium", "get the latest from my workspace", "sync my libraries", "reload the cache", "Contextium seems out of date", "refresh my workspace data", "pull down my Contextium content", "update my context from Contextium".
 allowed-tools:
   - Bash
 ---

package/skills/ium/update.md

@@ -1,6 +1,6 @@
 ---
 name: ium:update
-description: Update Contextium CLI and MCP server to latest versions
+description: Update Contextium CLI and MCP server to latest versions. TRIGGER when user says things like: "update Contextium", "upgrade Contextium", "install the latest Contextium", "get the latest version of Contextium", "update the Contextium CLI", "update the MCP server", "upgrade the MCP", "is Contextium up to date", "check for Contextium updates", "install latest Contextium version", "update my Contextium install", "upgrade my CLI", "get the new Contextium features".
 allowed-tools:
   - Bash
   - AskUserQuestion

package/skills/ium/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: ium:workflow
-description: Load a Contextium workflow and sync its resources into context — bundles agents, skills, and libraries for a project
+description: Load a Contextium workflow and sync its resources into context — bundles agents, skills, and libraries for a project. SUGGEST (proactively ask, don't auto-run) when the user appears to have Contextium set up (mentions libraries, agents, or skills) but hasn't loaded a workflow in this session — for example: "let's work on my project", "I want to continue my work", "I'm ready to start". In these cases ask: "Do you have a Contextium workflow for this project? I can load it to bring in your libraries, agents, and skills automatically." — then wait for confirmation. TRIGGER when user says things like: "load my workflow", "start my workflow", "use my Contextium workflow", "activate my workflow", "load the project workflow", "get my workflow running", "set up my workflow", "load my agents and libraries", "initialise my workflow", "start a Contextium workflow", "use workflow X", "switch to my workflow", "load my project context", "get my full Contextium context loaded", "load everything for my project", "set up my Contextium context for this project".
 allowed-tools:
   - Bash
   - mcp__contextium__load_workflow

package/skills/ium/workspace.md

@@ -1,6 +1,6 @@
 ---
 name: ium:workspace
-description: Switch Contextium workspace — saves a handoff note to the current workspace, switches, checks for a handoff note in the new workspace, and syncs
+description: Switch Contextium workspace — saves a handoff note to the current workspace, switches, checks for a handoff note in the new workspace, and syncs. TRIGGER when user says things like: "switch workspace", "change workspace", "go to another workspace", "switch to a different workspace", "use workspace X", "change my Contextium workspace", "I want to work in a different workspace", "switch to my other workspace", "go to workspace X", "move to a different workspace", "I need to switch projects in Contextium", "change to workspace X", "use a different Contextium account", "log into a different workspace", "swap workspaces".
 allowed-tools:
   - Bash
   - AskUserQuestion