ultimate-pi 0.1.0

package/.agents/skills/compress/scripts/validate.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+import re
+from pathlib import Path
+
+URL_REGEX = re.compile(r"https?://[^\s)]+")
+FENCE_OPEN_REGEX = re.compile(r"^(\s{0,3})(`{3,}|~{3,})(.*)$")
+HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
+BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
+
+# crude but effective path detection
+# Requires either a path prefix (./ ../ / or drive letter) or a slash/backslash within the match
+PATH_REGEX = re.compile(r"(?:\./|\.\./|/|[A-Za-z]:\\)[\w\-/\\\.]+|[\w\-\.]+[/\\][\w\-/\\\.]+")
+
+
+class ValidationResult:
+    def __init__(self):
+        self.is_valid = True
+        self.errors = []
+        self.warnings = []
+
+    def add_error(self, msg):
+        self.is_valid = False
+        self.errors.append(msg)
+
+    def add_warning(self, msg):
+        self.warnings.append(msg)
+
+
+def read_file(path: Path) -> str:
+    return path.read_text(errors="ignore")
+
+
+# ---------- Extractors ----------
+
+
+def extract_headings(text):
+    return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
+
+
+def extract_code_blocks(text):
+    """Line-based fenced code block extractor.
+
+    Handles ``` and ~~~ fences with variable length (CommonMark: closing
+    fence must use same char and be at least as long as opening). Supports
+    nested fences (e.g. an outer 4-backtick block wrapping inner 3-backtick
+    content).
+    """
+    blocks = []
+    lines = text.split("\n")
+    i = 0
+    n = len(lines)
+    while i < n:
+        m = FENCE_OPEN_REGEX.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        fence_char = m.group(2)[0]
+        fence_len = len(m.group(2))
+        open_line = lines[i]
+        block_lines = [open_line]
+        i += 1
+        closed = False
+        while i < n:
+            close_m = FENCE_OPEN_REGEX.match(lines[i])
+            if (
+                close_m
+                and close_m.group(2)[0] == fence_char
+                and len(close_m.group(2)) >= fence_len
+                and close_m.group(3).strip() == ""
+            ):
+                block_lines.append(lines[i])
+                closed = True
+                i += 1
+                break
+            block_lines.append(lines[i])
+            i += 1
+        if closed:
+            blocks.append("\n".join(block_lines))
+        # Unclosed fences are silently skipped — they indicate malformed markdown
+        # and including them would cause false-positive validation failures.
+    return blocks
+
+
+def extract_urls(text):
+    return set(URL_REGEX.findall(text))
+
+
+def extract_paths(text):
+    return set(PATH_REGEX.findall(text))
+
+
+def count_bullets(text):
+    return len(BULLET_REGEX.findall(text))
+
+
+# ---------- Validators ----------
+
+
+def validate_headings(orig, comp, result):
+    h1 = extract_headings(orig)
+    h2 = extract_headings(comp)
+
+    if len(h1) != len(h2):
+        result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
+
+    if h1 != h2:
+        result.add_warning("Heading text/order changed")
+
+
+def validate_code_blocks(orig, comp, result):
+    c1 = extract_code_blocks(orig)
+    c2 = extract_code_blocks(comp)
+
+    if c1 != c2:
+        result.add_error("Code blocks not preserved exactly")
+
+
+def validate_urls(orig, comp, result):
+    u1 = extract_urls(orig)
+    u2 = extract_urls(comp)
+
+    if u1 != u2:
+        result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
+
+
+def validate_paths(orig, comp, result):
+    p1 = extract_paths(orig)
+    p2 = extract_paths(comp)
+
+    if p1 != p2:
+        result.add_warning(f"Path mismatch: lost={p1 - p2}, added={p2 - p1}")
+
+
+def validate_bullets(orig, comp, result):
+    b1 = count_bullets(orig)
+    b2 = count_bullets(comp)
+
+    if b1 == 0:
+        return
+
+    diff = abs(b1 - b2) / b1
+
+    if diff > 0.15:
+        result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
+
+
+# ---------- Main ----------
+
+
+def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
+    result = ValidationResult()
+
+    orig = read_file(original_path)
+    comp = read_file(compressed_path)
+
+    validate_headings(orig, comp, result)
+    validate_code_blocks(orig, comp, result)
+    validate_urls(orig, comp, result)
+    validate_paths(orig, comp, result)
+    validate_bullets(orig, comp, result)
+
+    return result
+
+
+# ---------- CLI ----------
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 3:
+        print("Usage: python validate.py <original> <compressed>")
+        sys.exit(1)
+
+    orig = Path(sys.argv[1]).resolve()
+    comp = Path(sys.argv[2]).resolve()
+
+    res = validate(orig, comp)
+
+    print(f"\nValid: {res.is_valid}")
+
+    if res.errors:
+        print("\nErrors:")
+        for e in res.errors:
+            print(f"  - {e}")
+
+    if res.warnings:
+        print("\nWarnings:")
+        for w in res.warnings:
+            print(f"  - {w}")

package/.agents/skills/context7-cli/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: context7-cli
+description: Use the ctx7 CLI to fetch library documentation, manage AI coding skills, and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent.
+---
+
+# ctx7 CLI
+
+The Context7 CLI does three things: fetches up-to-date library documentation, manages AI coding skills, and sets up Context7 MCP for your editor.
+
+Make sure the CLI is up to date before running commands:
+
+```bash
+npm install -g ctx7@latest
+```
+
+Or run directly without installing:
+
+```bash
+npx ctx7@latest <command>
+```
+
+## What this skill covers
+
+- **[Documentation](references/docs.md)** — Fetch current docs for any library. Use when writing code, verifying API signatures, or when training data may be outdated.
+- **[Skills management](references/skills.md)** — Install, search, suggest, list, remove, and generate AI coding skills.
+- **[Setup](references/setup.md)** — Configure Context7 MCP for Claude Code / Cursor / OpenCode.
+
+## Quick Reference
+
+```bash
+# Documentation
+ctx7 library <name> <query>           # Step 1: resolve library ID
+ctx7 docs <libraryId> <query>         # Step 2: fetch docs
+ctx7 docs <libraryId> <query> --research  # Retry with deep research if the default answer didn't satisfy
+
+# Skills
+ctx7 skills install /owner/repo       # Install from a repo (interactive)
+ctx7 skills install /owner/repo name  # Install a specific skill
+ctx7 skills search <keywords>         # Search the registry
+ctx7 skills suggest                   # Auto-suggest based on project deps
+ctx7 skills list                      # List installed skills
+ctx7 skills remove <name>             # Uninstall a skill
+ctx7 skills generate                  # Generate a custom skill with AI (requires login)
+
+# Setup
+ctx7 setup                            # Configure Context7 MCP (interactive)
+ctx7 login                            # Log in for higher rate limits + skill generation
+ctx7 whoami                           # Check current login status
+```
+
+## Authentication
+
+```bash
+ctx7 login               # Opens browser for OAuth
+ctx7 login --no-browser  # Prints URL instead of opening browser
+ctx7 logout              # Clear stored tokens
+ctx7 whoami              # Show current login status (name + email)
+```
+
+Most commands work without login. Exceptions: `skills generate` always requires it; `ctx7 setup` requires it unless `--api-key` or `--oauth` is passed. Login also unlocks higher rate limits on docs commands.
+
+Set an API key via environment variable to skip interactive login entirely:
+
+```bash
+export CONTEXT7_API_KEY=your_key
+```
+
+## Common Mistakes
+
+- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
+- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
+- Repository format for skills is `/owner/repo` — e.g., `ctx7 skills install /anthropics/skills`
+- `skills generate` requires login — run `ctx7 login` first

package/.agents/skills/context7-cli/references/docs.md

@@ -0,0 +1,121 @@
+# Documentation Commands
+
+Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Two-step workflow: resolve the library name to get its ID, then query docs using that ID.
+
+If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`.
+
+## Step 1: Resolve a Library
+
+Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
+
+```bash
+ctx7 library react "How to clean up useEffect with async operations"
+ctx7 library nextjs "How to set up app router with middleware"
+ctx7 library prisma "How to define one-to-many relations with cascade delete"
+```
+
+Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+### Result fields
+
+Each result includes:
+
+- **Library ID** — Context7-compatible identifier (format: `/org/project`)
+- **Name** — Library or package name
+- **Description** — Short summary
+- **Code Snippets** — Number of available code examples
+- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
+- **Benchmark Score** — Quality indicator (100 is the highest score)
+- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
+
+### Selection process
+
+1. Analyze the query to understand what library/package the user is looking for
+2. Select the most relevant match based on:
+   - Name similarity to the query (exact matches prioritized)
+   - Description relevance to the query's intent
+   - Documentation coverage (prioritize libraries with higher Code Snippet counts)
+   - Source reputation (consider libraries with High or Medium reputation more authoritative)
+   - Benchmark score (higher is better, 100 is the maximum)
+3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
+4. If no good matches exist, clearly state this and suggest query refinements
+5. For ambiguous queries, request clarification before proceeding with a best-guess match
+
+IMPORTANT: Do not call `ctx7 library` more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.
+
+### Version-specific IDs
+
+If the user mentions a specific version, use a version-specific library ID:
+
+```bash
+# General (latest indexed)
+ctx7 docs /vercel/next.js "How to set up app router"
+
+# Version-specific
+ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+```
+
+The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
+
+```bash
+# Output as JSON for scripting
+ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
+```
+
+## Step 2: Query Documentation
+
+Retrieves up-to-date documentation and code examples for the resolved library.
+
+You must call `ctx7 library` first to obtain the exact Context7-compatible library ID required to use this command, UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
+
+```bash
+ctx7 docs /facebook/react "How to clean up useEffect with async operations"
+ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
+ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
+```
+
+IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.
+
+### Retry with `--research` if you weren't satisfied
+
+If the default `ctx7 docs` answer didn't satisfy, re-run the same command **with `--research`** before giving up or answering from training data. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default — use it as a targeted retry.
+
+```bash
+ctx7 docs /vercel/next.js "How does middleware matcher handle dynamic segments in v15?" --research
+```
+
+### Writing good queries
+
+The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+| Quality | Example |
+|---------|---------|
+| Good | `"How to set up authentication with JWT in Express.js"` |
+| Good | `"React useEffect cleanup function with async operations"` |
+| Bad | `"auth"` |
+| Bad | `"hooks"` |
+
+Use the user's full question as the query when possible — vague one-word queries return generic results.
+
+The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
+
+```bash
+# Output as structured JSON
+ctx7 docs /facebook/react "How to use hooks for state management" --json
+
+# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
+ctx7 docs /facebook/react "How to use hooks for state management" | head -50
+ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A5 "middleware"
+```
+
+## Authentication
+
+Works without authentication. For higher rate limits:
+
+```bash
+# Option A: environment variable
+export CONTEXT7_API_KEY=your_key
+
+# Option B: OAuth login
+ctx7 login
+```

package/.agents/skills/context7-cli/references/setup.md

@@ -0,0 +1,43 @@
+# Setup
+
+## ctx7 setup
+
+One-time command to configure Context7 for your AI coding agent. Prompts for mode on first run:
+- **MCP server** — registers the Context7 MCP server so the agent can call tools natively
+- **CLI + Skills** — installs a `find-docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required)
+
+```bash
+ctx7 setup                     # Interactive — prompts for mode, then agent/install target
+ctx7 setup --mcp               # Skip prompt, use MCP server mode
+ctx7 setup --cli               # Skip prompt, use CLI + Skills mode
+
+# MCP mode — target a specific agent
+ctx7 setup --claude            # Claude Code only
+ctx7 setup --cursor            # Cursor only
+ctx7 setup --opencode          # OpenCode only
+
+# CLI + Skills mode — target a specific install location
+ctx7 setup --cli --claude      # Claude Code (~/.claude/skills)
+ctx7 setup --cli --cursor      # Cursor (~/.cursor/skills)
+ctx7 setup --cli --universal   # Universal (~/.agents/skills)
+ctx7 setup --cli --antigravity # Antigravity (~/.config/agent/skills)
+
+ctx7 setup --project           # Configure current project instead of globally
+ctx7 setup --yes               # Skip confirmation prompts
+```
+
+**Authentication options:**
+```bash
+ctx7 setup --api-key YOUR_KEY  # Use an existing API key (both MCP and CLI + Skills mode)
+ctx7 setup --oauth             # OAuth endpoint — MCP mode only (IDE handles the auth flow)
+```
+
+Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. MCP mode additionally generates a new API key after login. `--oauth` is MCP-only.
+
+**What gets written — MCP mode:**
+- MCP server entry in the agent's config file (`.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, `.opencode.json` for OpenCode)
+- A Context7 rule file instructing the agent to use Context7 for library docs
+- A `context7-mcp` skill in the agent's skills directory
+
+**What gets written — CLI + Skills mode:**
+- A `find-docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commands

package/.agents/skills/context7-cli/references/skills.md

@@ -0,0 +1,118 @@
+# Skills Commands
+
+Manage AI coding skills from the Context7 registry. Skills are Markdown files that teach AI coding agents best practices, patterns, and workflows for specific libraries or tasks.
+
+## Install
+
+Install skills from any GitHub repository. Repository format is always `/owner/repo`.
+
+```bash
+ctx7 skills install /anthropics/skills           # Interactive — pick from a list
+ctx7 skills install /anthropics/skills pdf        # Install a specific skill by name
+ctx7 skills install /anthropics/skills --all      # Install everything without prompting
+```
+
+Target a specific IDE with a flag:
+```bash
+ctx7 skills install /anthropics/skills pdf --claude     # Claude Code only
+ctx7 skills install /anthropics/skills pdf --cursor     # Cursor only
+ctx7 skills install /anthropics/skills pdf --universal  # Universal (.agents/skills/)
+ctx7 skills install /anthropics/skills --all --global   # All skills, global install
+```
+
+Alias: `ctx7 si /anthropics/skills pdf`
+
+## Search
+
+Find skills across the entire registry by keyword. Shows an interactive list with install counts and trust scores. Select to install.
+
+```bash
+ctx7 skills search pdf
+ctx7 skills search typescript testing
+ctx7 skills search react nextjs
+```
+
+Alias: `ctx7 ss pdf`
+
+## Suggest
+
+Auto-detects your project dependencies and recommends relevant skills from the registry.
+
+```bash
+ctx7 skills suggest           # Scan current project, install to project
+ctx7 skills suggest --global  # Install suggestions globally
+ctx7 skills suggest --claude  # Target Claude Code only
+```
+
+Reads `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`. Falls back to suggesting `ctx7 skills search` if no dependencies are detected.
+
+Alias: `ctx7 ssg`
+
+## Generate (AI-powered)
+
+Generate a custom skill tailored to your stack using AI. **Requires login.**
+
+```bash
+ctx7 skills generate
+ctx7 skills generate --claude   # Install directly to Claude Code
+ctx7 skills generate --global   # Install to global skills
+```
+
+Interactive flow:
+1. Describe the expertise you want (e.g., "OAuth authentication with NextAuth.js")
+2. Select relevant libraries from search results
+3. Answer 3 clarifying questions to focus the skill
+4. Review the generated skill, request changes if needed
+5. Choose where to install it
+
+**Limits:** Free accounts get 6 generations/week, Pro accounts get 10.
+
+Aliases: `ctx7 skills gen`, `ctx7 skills g`
+
+## List
+
+Show all installed skills for the current project or globally.
+
+```bash
+ctx7 skills list                  # Current project (all detected IDEs)
+ctx7 skills list --claude         # Claude Code only
+ctx7 skills list --global         # Global skills
+ctx7 skills list --global --claude # Global Claude Code skills
+```
+
+## Remove
+
+Uninstall a skill by name.
+
+```bash
+ctx7 skills remove pdf
+ctx7 skills remove pdf --claude   # From Claude Code only
+ctx7 skills remove pdf --global   # From global skills
+```
+
+Aliases: `ctx7 skills rm`, `ctx7 skills delete`
+
+## Info
+
+Browse all skills in a repository without installing — useful for previewing what's available.
+
+```bash
+ctx7 skills info /anthropics/skills
+```
+
+Output shows each skill name, description, and URL, plus quick install commands.
+
+## IDE Flags
+
+All skills commands accept these flags to target a specific AI coding assistant:
+
+| Flag | Directory | Used by |
+|------|-----------|---------|
+| `--universal` | `.agents/skills/` | Amp, Codex, Gemini CLI, OpenCode, GitHub Copilot |
+| `--claude` | `.claude/skills/` | Claude Code |
+| `--cursor` | `.cursor/skills/` | Cursor |
+| `--antigravity` | `.agent/skills/` | Antigravity |
+
+Without a flag, the CLI prompts you to select one or more targets interactively.
+
+Add `--global` to any flag to install in your home directory instead of the current project.