@mxalbert/context-mode 2.0.0

package/skills/context-mode/references/patterns-shell.md

@@ -0,0 +1,277 @@
+# Shell Patterns for execute
+
+Practical patterns for using `execute` with `language: shell`.
+Best for piping, filtering, and leveraging native OS tools.
+
+---
+
+## Build Output Filtering
+
+### Capture build errors only
+
+```shell
+npm run build 2>&1 | tee /tmp/build-output.txt
+EXIT_CODE=${PIPESTATUS[0]}
+
+echo "=== Build Result ==="
+echo "Exit code: $EXIT_CODE"
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo ""
+  echo "=== Errors ==="
+  grep -iE '(error|failed|FAIL)' /tmp/build-output.txt | head -50
+  echo ""
+  echo "=== Warnings ==="
+  grep -iE '(warning|warn)' /tmp/build-output.txt | head -20
+else
+  echo "Build succeeded."
+  echo ""
+  echo "=== Warnings (if any) ==="
+  grep -iE '(warning|warn)' /tmp/build-output.txt | head -10
+fi
+
+echo ""
+echo "=== Output Size ==="
+wc -l < /tmp/build-output.txt | xargs -I{} echo "{} total lines of output"
+rm -f /tmp/build-output.txt
+```
+> summary_prompt: "Report build success/failure, list all errors with file paths, and count warnings"
+> timeout_ms: 120000
+
+### TypeScript compilation check
+
+```shell
+npx tsc --noEmit 2>&1 | tee /tmp/tsc-output.txt
+EXIT_CODE=${PIPESTATUS[0]}
+
+echo "=== TypeScript Check ==="
+echo "Exit code: $EXIT_CODE"
+
+TOTAL_ERRORS=$(grep -c 'error TS' /tmp/tsc-output.txt 2>/dev/null || echo 0)
+echo "Total errors: $TOTAL_ERRORS"
+
+if [ "$TOTAL_ERRORS" -gt 0 ]; then
+  echo ""
+  echo "=== Errors by Code ==="
+  grep -oP 'error TS\d+' /tmp/tsc-output.txt | sort | uniq -c | sort -rn | head -20
+
+  echo ""
+  echo "=== Errors by File ==="
+  grep 'error TS' /tmp/tsc-output.txt | cut -d'(' -f1 | sort | uniq -c | sort -rn | head -20
+
+  echo ""
+  echo "=== First 30 Errors ==="
+  grep 'error TS' /tmp/tsc-output.txt | head -30
+fi
+
+rm -f /tmp/tsc-output.txt
+```
+> summary_prompt: "Report type error count, most common error codes, and most affected files"
+> timeout_ms: 60000
+
+---
+
+## Test Result Summarization
+
+### Jest test summary
+
+```shell
+npx jest --verbose 2>&1 | tee /tmp/test-output.txt
+EXIT_CODE=${PIPESTATUS[0]}
+
+echo ""
+echo "=== Test Summary ==="
+echo "Exit code: $EXIT_CODE"
+
+# Extract summary line
+grep -E '(Tests:|Test Suites:|Snapshots:|Time:)' /tmp/test-output.txt
+
+echo ""
+echo "=== Failed Tests ==="
+grep -A 2 'FAIL ' /tmp/test-output.txt | head -40
+
+echo ""
+echo "=== Slow Tests (if reported) ==="
+grep -i 'slow' /tmp/test-output.txt | head -10
+
+rm -f /tmp/test-output.txt
+```
+> summary_prompt: "Report pass/fail ratio, list all failing test names with suite, note any slow tests"
+> timeout_ms: 120000
+
+### Pytest summary
+
+```shell
+python -m pytest --tb=short -q 2>&1 | tee /tmp/pytest-output.txt
+EXIT_CODE=${PIPESTATUS[0]}
+
+echo ""
+echo "=== Pytest Summary ==="
+echo "Exit code: $EXIT_CODE"
+
+# Last 20 lines usually contain the summary
+tail -20 /tmp/pytest-output.txt
+
+echo ""
+echo "=== Failures ==="
+grep -E '(FAILED|ERROR)' /tmp/pytest-output.txt | head -30
+
+rm -f /tmp/pytest-output.txt
+```
+> summary_prompt: "Report test results, list all failures with file and test name"
+> timeout_ms: 120000
+
+---
+
+## Log File Analysis
+
+### Filter application logs by severity
+
+```shell
+LOG_FILE="${1:-/var/log/app.log}"
+
+echo "=== Log File: $LOG_FILE ==="
+echo "Total lines: $(wc -l < "$LOG_FILE")"
+echo ""
+
+echo "=== Level Distribution ==="
+grep -oE '\b(DEBUG|INFO|WARN|ERROR|FATAL)\b' "$LOG_FILE" | sort | uniq -c | sort -rn
+
+echo ""
+echo "=== Last 20 Errors ==="
+grep -i 'ERROR\|FATAL' "$LOG_FILE" | tail -20
+
+echo ""
+echo "=== Error Timeline (hourly) ==="
+grep -i 'ERROR' "$LOG_FILE" | grep -oE '\d{4}-\d{2}-\d{2} \d{2}' | sort | uniq -c | tail -24
+```
+> summary_prompt: "Report error frequency, identify patterns, and note any error spikes"
+
+### Analyze access logs
+
+```shell
+LOG_FILE="${1:-/var/log/access.log}"
+
+echo "=== Access Log Summary ==="
+echo "Total requests: $(wc -l < "$LOG_FILE")"
+
+echo ""
+echo "=== HTTP Status Codes ==="
+awk '{print $9}' "$LOG_FILE" | sort | uniq -c | sort -rn | head -10
+
+echo ""
+echo "=== Top 20 Paths ==="
+awk '{print $7}' "$LOG_FILE" | sort | uniq -c | sort -rn | head -20
+
+echo ""
+echo "=== Top 10 IPs ==="
+awk '{print $1}' "$LOG_FILE" | sort | uniq -c | sort -rn | head -10
+
+echo ""
+echo "=== 5xx Errors ==="
+awk '$9 ~ /^5/' "$LOG_FILE" | tail -20
+
+echo ""
+echo "=== Requests per Hour ==="
+awk '{print $4}' "$LOG_FILE" | cut -d: -f1-2 | sort | uniq -c | tail -24
+```
+> summary_prompt: "Report traffic patterns, error rates, most hit endpoints, and suspicious IPs"
+
+---
+
+## Directory Size and Structure Analysis
+
+### Project structure overview
+
+```shell
+echo "=== Directory Structure ==="
+find . -maxdepth 3 -type d \
+  ! -path '*/node_modules/*' \
+  ! -path '*/.git/*' \
+  ! -path '*/dist/*' \
+  ! -path '*/.next/*' \
+  ! -path '*/__pycache__/*' \
+  | sort
+
+echo ""
+echo "=== File Type Distribution ==="
+find . -type f \
+  ! -path '*/node_modules/*' \
+  ! -path '*/.git/*' \
+  ! -path '*/dist/*' \
+  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
+
+echo ""
+echo "=== Largest Files (top 20) ==="
+find . -type f \
+  ! -path '*/node_modules/*' \
+  ! -path '*/.git/*' \
+  -exec ls -la {} \; | sort -k5 -rn | head -20 | awk '{print $5, $9}'
+
+echo ""
+echo "=== Directory Sizes ==="
+du -sh */ 2>/dev/null | sort -rh | head -15
+```
+> summary_prompt: "Describe the project structure, identify large files that may need attention, report file type distribution"
+
+### Disk usage investigation
+
+```shell
+echo "=== Top-Level Disk Usage ==="
+du -sh */ 2>/dev/null | sort -rh
+
+echo ""
+echo "=== node_modules Size ==="
+if [ -d "node_modules" ]; then
+  du -sh node_modules
+  echo ""
+  echo "=== Largest node_modules packages ==="
+  du -sh node_modules/*/ 2>/dev/null | sort -rh | head -20
+else
+  echo "No node_modules directory"
+fi
+
+echo ""
+echo "=== Build Artifacts ==="
+for dir in dist build .next out .cache; do
+  if [ -d "$dir" ]; then
+    echo "  $dir: $(du -sh "$dir" | cut -f1)"
+  fi
+done
+
+echo ""
+echo "=== Git Objects Size ==="
+if [ -d ".git" ]; then
+  du -sh .git
+fi
+```
+> summary_prompt: "Report total project size, largest contributors, and recommend cleanup targets"
+
+---
+
+## Git Analysis
+
+### Commit activity analysis
+
+```shell
+echo "=== Recent Commits (last 30 days) ==="
+git log --since="30 days ago" --oneline | wc -l | xargs -I{} echo "{} commits in last 30 days"
+
+echo ""
+echo "=== Commits by Author ==="
+git shortlog -sn --since="30 days ago" | head -15
+
+echo ""
+echo "=== Most Changed Files (last 30 days) ==="
+git log --since="30 days ago" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
+
+echo ""
+echo "=== Branches ==="
+echo "Local: $(git branch | wc -l | xargs)"
+echo "Remote: $(git branch -r | wc -l | xargs)"
+
+echo ""
+echo "=== Stale Branches (merged, excluding main/master) ==="
+git branch --merged main 2>/dev/null | grep -v 'main\|master\|\*' | head -10
+```
+> summary_prompt: "Report development velocity, active contributors, hotspot files, and cleanup opportunities"

package/skills/ctx-doctor/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ctx-doctor
+description: |
+  Run context-mode diagnostics. Checks runtimes, hooks, FTS5,
+  plugin registration, npm and marketplace versions.
+  Trigger: /context-mode:ctx-doctor
+user-invocable: true
+---
+
+# Context Mode Doctor
+
+Run diagnostics and display results directly in the conversation.
+
+## Instructions
+
+1. Call the `ctx_doctor` MCP tool directly. It runs all checks server-side and returns a plain-text status report.
+2. Display the results verbatim — they are already formatted with plain-text status prefixes: `[OK]` PASS, `[FAIL]` FAIL, `[WARN]` WARN. Renderer-safe (no markdown task-list syntax) for cross-client compatibility (e.g., Z.ai GLM).
+3. **Fallback** (only if MCP tool call fails): Derive the **plugin root** from this skill's base directory (go up 2 levels — remove `/skills/ctx-doctor`), then run with Bash:
+   ```
+   CLI="<PLUGIN_ROOT>/cli.bundle.mjs"; [ ! -f "$CLI" ] && CLI="<PLUGIN_ROOT>/build/cli.js"; node "$CLI" doctor
+   ```
+   Re-display results verbatim with the same `[OK]`/`[FAIL]`/`[WARN]` prefixes.

package/skills/ctx-index/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ctx-index
+description: |
+  Index a local file or directory into context-mode's persistent FTS5 knowledge base
+  so future ctx_search calls can retrieve focused snippets without rereading raw files.
+  Trigger: /context-mode:ctx-index
+user-invocable: true
+---
+
+# Context Mode Index
+
+Index local project content for later search.
+
+## Instructions
+
+1. Prefer the `ctx_index` MCP tool when it is available.
+2. Ask for a path only if the user did not provide one and the current project root is ambiguous.
+3. Use `path`, not large inline `content`, so file bytes do not enter the conversation.
+4. For repository indexing, pass conservative bounds and a clear source label:
+
+```javascript
+ctx_index({
+  path: ".",
+  source: "project:<name>",
+  maxDepth: 5,
+  maxFiles: 200
+})
+```
+
+5. If MCP tools are unavailable, fall back to the CLI:
+
+```bash
+context-mode index . --source project:<name>
+```
+
+6. Report the indexed source label, file count or section count, and the matching search command:
+
+```javascript
+ctx_search({ source: "project:<name>", queries: ["..."] })
+```
+
+## Safety
+
+- Do not index dependency directories, build outputs, secrets, or generated artifacts.
+- Prefer `--exclude` or `exclude` for project-specific noisy paths.
+- For broad repos, ask the user before raising `maxFiles` above 500.

package/skills/ctx-insight/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ctx-insight
+description: |
+  Open the context-mode Insight dashboard in your default browser.
+  Insight is the hosted analytics layer for AI-assisted engineering teams —
+  per-engineer productive rate, retry waste, blocker detection, role-narrowed views.
+  Trigger: /context-mode:ctx-insight
+user-invocable: true
+---
+
+# Context Mode Insight
+
+Open the hosted Insight dashboard in the user's default browser.
+
+## Instructions
+
+1. Call the `ctx_insight` MCP tool (no parameters). It opens
+   <https://context-mode.com/insight> in the default browser and returns a
+   confirmation line.
+2. Display the tool's output to the user.
+3. Tell the user:
+   - "Insight opened at https://context-mode.com/insight"
+   - The landing page at context-mode.com/insight is the single source of truth for sign-in and pricing details.
+   - If the browser did not open automatically, share the URL so they can open it manually.

package/skills/ctx-purge/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ctx-purge
+description: |
+  Purge the context-mode knowledge base. Permanently deletes all indexed content
+  and resets session stats. This is destructive and cannot be undone.
+  Trigger: /context-mode:ctx-purge
+user-invocable: true
+---
+
+# Context Mode Purge
+
+Permanently deletes session data for this project. Two scopes are supported (issue #520):
+
+- **Project scope** (`scope: "project"`): wipes EVERYTHING — knowledge base, all session DB rows for every session, events markdown, and stats.
+- **Session scope** (`sessionId: "<id>"` or `scope: "session"`): wipes ONLY the matching session's rows + FTS5 chunks. Sibling sessions, project stats, and the FTS5 store file are preserved.
+
+## Instructions
+
+1. **Decide the scope first** with the user:
+   - "Wipe just one session?" → ask for the `sessionId`.
+   - "Wipe the whole project?" → confirm scope:'project' (this is the destructive, irreversible default).
+2. **Warn the user about scope:'project'**. Everything will be deleted:
+   - FTS5 knowledge base (all indexed content from `ctx_index`, `ctx_fetch_and_index`, `ctx_batch_execute`)
+   - Session events DB (analytics, metadata, resume snapshots) for ALL sessions in the project
+   - Session events markdown file
+   - In-memory session stats + persisted stats file
+3. Call the `mcp__context-mode__ctx_purge` MCP tool with the chosen parameters:
+   - Scoped: `{ confirm: true, sessionId: "<id>" }` — implies scope:'session'.
+   - Project: `{ confirm: true, scope: "project" }` — explicit destructive form.
+   - Bare `{ confirm: true }` still works but emits a deprecation warning. Prefer the explicit forms.
+4. Report the result to the user — the response lists exactly what was deleted and (for scoped purges) confirms that other sessions and project stats were preserved.
+
+## Schema rules
+
+- `confirm: true` is always required.
+- `sessionId` and `scope: "project"` together is REJECTED as ambiguous (the sessionId implies session scope; combining with project scope contradicts intent).
+- `scope: "session"` without `sessionId` throws — sessionId is required.
+
+## When to Use
+
+- **Scoped (per-session)**: scratch acceptance scenarios, drill replays, isolating a polluted session without losing the main working session's stats.
+- **Project**: KB contains stale or incorrect content polluting search results, switching between unrelated projects in the same session, completely fresh start.
+
+## Important
+
+- `ctx_purge` is the **only** way to delete session data. No other mechanism exists.
+- `ctx_stats` is read-only — shows statistics only.
+- `/clear` and `/compact` do NOT affect any context-mode data.
+- There is no undo. Re-index content if you need it again.

package/skills/ctx-search/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ctx-search
+description: |
+  Search context-mode's persistent FTS5 knowledge base for previously indexed
+  local project content, documentation, or session memory.
+  Trigger: /context-mode:ctx-search
+user-invocable: true
+---
+
+# Context Mode Search
+
+Search indexed content without rereading raw sources into conversation context.
+
+## Instructions
+
+1. Prefer the `ctx_search` MCP tool when it is available.
+2. Batch all related questions in one `queries` array.
+3. Scope with `source` when the user names a project or indexed label.
+4. Use short, specific queries of two to four technical terms.
+
+```javascript
+ctx_search({
+  source: "project:<name>",
+  queries: ["authentication middleware", "token refresh"],
+  limit: 5
+})
+```
+
+5. If MCP tools are unavailable, fall back to the CLI:
+
+```bash
+context-mode search "authentication middleware" --source project:<name> --limit 5
+```
+
+6. If the index is empty, tell the user to run `/context-mode:ctx-index` or `context-mode index <path>` first.

package/skills/ctx-stats/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ctx-stats
+description: |
+  Show how much context window context-mode saved this session.
+  Displays token consumption, context savings ratio, and per-tool breakdown.
+  Read-only — shows stats only, no reset capability.
+  To wipe the knowledge base entirely, use ctx_purge instead.
+  Trigger: /context-mode:ctx-stats
+user-invocable: true
+---
+
+# Context Mode Stats
+
+Show context savings for the current session.
+
+## Instructions
+
+1. Call the `mcp__context-mode__ctx_stats` MCP tool (no parameters needed).
+2. **CRITICAL**: You MUST copy-paste the ENTIRE tool output as markdown text directly into your response message. Do NOT summarize, do NOT collapse, do NOT paraphrase. The user must see the full tables without pressing ctrl+o. Copy every line exactly as returned by the tool.
+3. After the full output, add ONE sentence highlighting the key savings metric, e.g.:
+   - "context-mode saved **12.4x** — 92% of data stayed in sandbox."
+   - If no data yet: "No context-mode calls yet this session."
+
+## Purge
+
+- **`ctx_purge(confirm: true)`** — Permanently deletes all indexed content from the knowledge base. Use `/context-mode:ctx-purge` for this.

package/skills/ctx-upgrade/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: ctx-upgrade
+description: |
+  Update context-mode from GitHub and fix hooks/settings.
+  Pulls latest, builds, installs, updates npm global, configures hooks.
+  Trigger: /context-mode:ctx-upgrade
+user-invocable: true
+---
+
+# Context Mode Upgrade
+
+Pull latest from GitHub and reinstall the plugin.
+
+## Instructions
+
+1. Call the `ctx_upgrade` MCP tool directly. It returns a shell command to execute.
+2. Run the returned command using your shell execution tool (Bash, shell_execute, etc.).
+3. Display results as a markdown checklist:
+   ```
+   ## context-mode upgrade
+   - [x] Pulled latest from GitHub
+   - [x] Built and installed v1.0.39
+   - [x] Hooks configured
+   - [x] Doctor: all checks PASS
+   ```
+   Use `[x]` for success, `[ ]` for failure. Show actual version numbers.
+4. Tell the user to **restart their session** to pick up the new version.
+5. **Fallback** (only if MCP tool call fails): Derive the **plugin root** from this skill's base directory (go up 2 levels — remove `/skills/ctx-upgrade`), then run with Bash:
+   ```
+   CLI="<PLUGIN_ROOT>/cli.bundle.mjs"; [ ! -f "$CLI" ] && CLI="<PLUGIN_ROOT>/build/cli.js"; node "$CLI" upgrade
+   ```