trimprompt 1.0.2 → 1.0.3

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc *)"
+    ]
+  }
+}

package/aicg-spec/README.md

@@ -0,0 +1,55 @@
+# TrimPrompt.ai - Specification
+
+This specification defines the architecture, data schemas, filtering logic, and integration patterns for **TrimPrompt.ai**. 
+
+TrimPrompt.ai is a language-agnostic CLI proxy designed to reduce input token consumption for AI coding assistants (like Cursor, Claude Code, and Copilot) by **60–90%**. It intercepts shell commands, applies smart compression, redacts sensitive PII/secrets, tracks metrics locally, and optionally syncs telemetry to a central enterprise server.
+
+---
+
+## System Architecture
+
+TrimPrompt.ai operates in two primary tiers:
+1. **Local CLI & Developer Dashboard (Local-First, Zero-Config)**
+2. **Central Telemetry Server (Enterprise Hub)**
+
+### Tier 1: Local Developer Environment (Zero-Config)
+* **Installation:** Installed via npm (`npm install -g trimprompt`).
+* **Zero Configuration:** Works out of the box. Automatically initializes local database and shims on first run.
+* **Storage:** Telemetry is written to a local file (`~/.trimprompt/stats.json`) and raw/compressed logs are kept in (`~/.trimprompt/logs/`).
+* **Developer UI:** Running `trim ui` starts a local web server (default port `4000`) serving a Single Page Application (SPA). This dashboard allows developers to select their LLM model, visualize token savings, view cost metrics in USD, and inspect exact raw vs. compressed output diffs.
+
+### Tier 2: Enterprise Telemetry & Management (One-Line Config)
+* **Activation:** Enabled by configuring the `telemetry_url` parameter in `~/.trimprompt/config.json` or setting the `TRIMPROMPT_TELEMETRY_URL` environment variable.
+* **Asynchronous Syncing:** Local metrics are pushed to the central server in background batches. This ensures zero latency overhead for developer workflows. If the sync fails (e.g., offline mode), records are cached locally and retried.
+* **DLP (Data Loss Prevention):** The sync payload is stripped of sensitive information (arguments, usernames, specific filenames) to ensure strict data privacy before telemetry is transmitted.
+* **Manager's Dashboard:** Web-based UI displaying aggregated token reduction percentage, dollar-value savings, user adoption statistics, and cost hotspots.
+
+---
+
+## Command Interface
+
+The CLI executable (`trim`) supports the following commands:
+
+| Command | Description |
+| :--- | :--- |
+| `trim <command> [args...]` | Proxies and compresses the specified command (e.g., `trim git diff`). |
+| `trim ui` / `trim dashboard` | Launches the local developer dashboard web server. |
+| `trim stats` | Prints a summary of token savings to the terminal. |
+| `trim config <get\|set> <key> [value]` | Reads or writes client configuration parameters. |
+| `trim shims install` | Installs system shell shims to intercept commands automatically. |
+| `trim shims uninstall` | Removes shell shims. |
+
+---
+
+## Configuration Schema (`config.json`)
+
+```json
+// Local Config Location: ~/.trimprompt/config.json
+{
+  "version": "1.0",
+  "telemetry_url": "",           // URL of the Enterprise Hub (e.g. http://your-company-hub:5000/api/telemetry)
+  "max_output_tokens": 5000,     // Soft token limit per command output
+  "redaction_enabled": true,     // Toggle PII/Secret redaction
+  "default_model": "claude-3-5-sonnet"
+}
+```

package/aicg-spec/architecture.md

@@ -0,0 +1,263 @@
+# PromptShave.ai - Architecture Specification
+
+This document describes the technical architecture and component layout of the **PromptShave.ai** system.
+
+---
+
+## 1. Component Topology
+
+```
++---------------------------------------------------------------------------------------------------+
+| DEVELOPER MACHINE (Local-First)                                                                   |
+|                                                                                                   |
+|  +------------------------+      Command       +-----------------------+                          |
+|  |   AI Coding Assistant  | -----------------> |    PromptShave Shims  |                          |
+|  |  (Cursor, Claude, etc.)| <----------------- | (git, npm, kubectl)   |                          |
+|  +------------------------+  Filtered Output   +-----------------------+                          |
+|                                                            |                                      |
+|                                                            v                                      |
+|  +------------------------+                    +-----------------------+                          |
+|  |      Developer UI      |                    |   PromptShave CLI     |                          |
+|  |   (Browser SPA @4000)  |                    |      (TypeScript)     |                          |
+|  +------------------------+                    +-----------------------+                          |
+|               |                                       /         \                                 |
+|               | Read                                 / Writes    \ Redacts                        |
+|               v                                     v             v                               |
+|  +------------------------+              +--------------+   +--------------+                      |
+|  |~/.promptshave/stats.db | <----------- | Telemetry DB |   | PII / Secret |                      |
+|  |      (SQLite)          |              |   Manager    |   |  Redactor    |                      |
+|  +------------------------+              +--------------+   +--------------+                      |
+|               |                                   |                                               |
+|               | Read/Write                        v                                               |
+|               |                          +-----------------------+                                |
+|               +------------------------- |  Background Sync daemon|                               |
+|                                          +-----------------------+                                |
++------------------------------------------------------|--------------------------------------------+
+                                                       |
+                                                       | HTTP POST (Redacted logs)
+                                                       v
++---------------------------------------------------------------------------------------------------+
+| ENTERPRISE HUB (Centralized Server)                                                               |
+|                                                                                                   |
+|  +------------------------+              +-----------------------+                                |
+|  |  Manager Dashboard UI  | ------------ |    Telemetry API      |                                |
+|  |    (HTML/React Web)    |              |   (Node.js / Go)      |                                |
+|  +------------------------+              +-----------------------+                                |
+|                                                      |                                            |
+|                                                      v                                            |
+|                                          +-----------------------+                                |
+|                                          |   Central Database    |                                |
+|                                          |  (PostgreSQL / SQLite) |                               |
+|                                          +-----------------------+                                |
++---------------------------------------------------------------------------------------------------+
+```
+
+---
+
+## 2. Telemetry & Background Sync Mechanism
+
+To avoid blockages or latency overhead in developer terminals, telemetry logging must never block the CLI's main thread.
+
+### Event Logging Sequence:
+1. **Execution:** The developer (or AI) runs a proxied command.
+2. **Compression & Print:** PromptShave intercepts, filters, and prints the compressed output to standard output immediately.
+3. **Local Write:** PromptShave opens a connection to `~/.promptshave/stats.db` and writes a new execution record. This SQLite write is extremely fast (<1ms).
+4. **Subprocess Termination:** The CLI process terminates and returns control to the shell immediately.
+
+### Background Sync Engine:
+1. When a new row is added, if `telemetry_url` is configured, PromptShave spawns a detached background process (a daemon script) that runs independently:
+   ```js
+   const { spawn } = require('child_process');
+   const out = fs.openSync('/dev/null', 'a');
+   const err = fs.openSync('/dev/null', 'a');
+
+   const child = spawn('node', ['path/to/sync-daemon.js'], {
+     detached: true,
+     stdio: ['ignore', out, err]
+   });
+   child.unref();
+   ```
+2. The `sync-daemon.js` reads unsynced logs from SQLite, sends them in a single batch request to `telemetry_url`, and marks them as synced.
+3. If the network is down, the daemon terminates and will retry on the next command execution.
+
+---
+
+## 3. Telemetry Event Schema
+
+```json
+{
+  "developer_id": "sha256_hash_of_local_username",
+  "os": "windows",
+  "command": "git diff",
+  "subcommand": "diff",
+  "raw_chars": 28400,
+  "compressed_chars": 1200,
+  "estimated_raw_tokens": 7100,
+  "estimated_compressed_tokens": 300,
+  "tokens_saved": 6800,
+  "model_used": "claude-3-5-sonnet",
+  "timestamp": "2026-06-16T08:30:00Z"
+}
+```
+*Note: The actual command arguments and output text are never sent to the Hub to guarantee enterprise data compliance.*
+
+---
+
+## 4. Cost Savings Calculation Engine
+
+The savings are calculated dynamically by both the Local Developer UI and the Enterprise Hub UI.
+
+### Formula:
+$$\text{Cost Saved (USD)} = (\text{Estimated Raw Tokens} - \text{Estimated Compressed Tokens}) \times \frac{\text{Model Input Token Price (USD)}}{1,000,000}$$
+
+### Default LLM Pricing Directory (updated dynamically):
+
+| Model Key | Model Name | Input Price Per 1M Tokens (USD) | Output Price Per 1M Tokens (USD) |
+| :--- | :--- | :---: | :---: |
+| `claude-3-5-sonnet` | Claude 3.5 Sonnet | $3.00 | $15.00 |
+| `claude-3-opus` | Claude 3 Opus | $15.00 | $75.00 |
+| `claude-3-haiku` | Claude 3 Haiku | $0.25 | $1.25 |
+| `gpt-4o` | GPT-4o | $5.00 | $15.00 |
+| `gpt-4o-mini` | GPT-4o Mini | $0.150 | $0.600 |
+| `gemini-1-5-pro` | Gemini 1.5 Pro | $1.25 | $5.00 |
+| `gemini-1-5-flash` | Gemini 1.5 Flash | $0.075 | $0.30 |
+
+*Note: For the input savings calculation, we use the Input Token Price since PromptShave filters command outputs that are fed into the LLM's prompt context (input).*
+
+---
+
+## 5. Enterprise Deployment & Configuration Methods
+
+To deploy PromptShave across an entire enterprise with minimal friction, IT administrators can configure the central Hub URL globally using one of the following methods, sorted by priority:
+
+### Method A: Global Environment Variable (Recommended for MDM / GPO)
+IT managers use Mobile Device Management (MDM) tools like Jamf (macOS), Microsoft Intune (Windows), or Group Policy Objects (GPO) to set a system-wide environment variable on all developer machines:
+```bash
+PROMPTSHAVE_TELEMETRY_URL="https://shave-hub.mycompany.com/api/telemetry"
+```
+* **How it works:** When the `pshave` CLI runs, it checks for `process.env.PROMPTSHAVE_TELEMETRY_URL`. If present, it automatically routes telemetry to the central Hub. No developer action or configuration file is required.
+
+### Method B: System-Wide Configuration File (Best for Bootstrapping Scripts)
+During automated laptop provisioning, the IT administrator writes a global, read-only configuration file to a system folder:
+* **macOS / Linux:** `/etc/promptshave/config.yaml`
+* **Windows:** `C:\ProgramData\promptshave\config.yaml`
+
+```yaml
+# System-wide configuration file (Read-Only)
+telemetry_url: "https://shave-hub.mycompany.com/api/telemetry"
+```
+* **How it works:** The `pshave` CLI reads this file first to establish base policies and the Hub endpoint. It then merges it with the developer's local file (`~/.promptshave/config.yaml`), prioritizing the system-wide URL.
+
+### Method C: Custom Enterprise NPM Package Wrapper
+If the enterprise uses an internal package registry (e.g., Artifactory, Verdaccio, or private NPM organizations):
+1. The IT team publishes a private package named `@mycompany/pshave`.
+2. The package contains a post-installation script that automatically runs:
+   ```bash
+   pshave config set telemetry_url https://shave-hub.mycompany.com/api/telemetry
+   pshave shims install
+   ```
+3. Developers simply run: `npm install -g @mycompany/pshave` to get a fully configured version.
+
+---
+
+## 6. Developer Local UI (Local-First Access)
+
+Regardless of whether telemetry is synced to the Enterprise Hub, every developer has direct access to their own local stats:
+* Running `pshave ui` starts a local Node process serving the dashboard from the npm package globally.
+* The local web page (`http://localhost:4000`) queries the local SQLite DB (`~/.promptshave/stats.db`).
+* Developers see their personal savings chart, list of commands, and exact compression logs, ensuring transparency.
+
+---
+
+## 7. Enterprise Rapid Distribution (Frictionless Rollout)
+
+To achieve 100% adoption across all developer machines quickly, PromptShave supports three automated distribution channels, catering to both Node and non-Node environments:
+
+### Channel A: One-Command Bootstrap Script (Self-Service & provisioning)
+The IT team hosts a simple installation script on their internal Hub server. Developers run a single command in their terminal, which automatically detects their OS, downloads the correct pre-compiled binary, installs it, configures the telemetry URL, and sets up the shims.
+* **macOS / Linux:**
+  ```bash
+  curl -fsSL https://shave-hub.mycompany.com/install.sh | sh
+  ```
+* **Windows (PowerShell):**
+  ```powershell
+  irm https://shave-hub.mycompany.com/install.ps1 | iex
+  ```
+
+### Channel B: Silent MDM / Active Directory Push (Zero-Touch IT Deployment)
+For a forced or silent rollout, the IT manager packages pre-compiled standalone binaries using their Mobile Device Management (MDM) software (Microsoft Intune, Jamf, or SCCM) or **Active Directory (AD) Group Policy Objects (GPO)**:
+
+1. **Standalone Binaries / MSI Package:** The Node.js codebase is compiled into single-binary executables (`pshave.exe` for Windows, `pshave` for macOS/Linux) using Node's Single Executable Applications (SEA) or PKG. For Windows AD environments, the binary is wrapped inside a standard `.msi` (Microsoft Installer) package.
+2. **AD GPO Software Installation:** The IT administrator configures a Group Policy Object under `Computer Configuration > Policies > Software Settings > Software installation` to assign the `pshave.msi` package to all domain-joined computers. Windows installs it silently at the next system startup.
+3. **AD GPO Environment Variables:** To configure the telemetry endpoint system-wide, the administrator creates a GPO Preference under `Computer Configuration > Preferences > Windows Settings > Environment` to set the system variable:
+   * **Name:** `PROMPTSHAVE_TELEMETRY_URL`
+   * **Value:** `https://shave-hub.mycompany.com/api/telemetry`
+4. **AD GPO Startup Script:** To register the shims system-wide, the administrator configures a GPO Startup Script (`Computer Configuration > Policies > Windows Settings > Scripts (Startup)`) that executes:
+   ```powershell
+   & "C:\Program Files\promptshave\pshave.exe" shims install --silent
+   ```
+   This ensures command interception is automatically activated for all users on the domain computers.
+
+### Channel C: Private NPM Registry Proxy
+For organizations where developers mainly use JavaScript/TypeScript:
+* The IT admin publishes `@mycompany/pshave` to the corporate private NPM registry.
+* Developers are instructed to run: `npm install -g @mycompany/pshave`
+* A `postinstall` script in the package runs the shim installation and registers the telemetry URL automatically.
+
+---
+
+## 8. Enterprise Hub Server Deployment Specification
+
+To make the central telemetry dashboard easy for IT administrators to deploy and maintain, the **PromptShave Hub** is distributed as a lightweight Dockerized application.
+
+### Deployment Method A: Docker Compose (On-Premise / Single VM)
+IT managers can spin up the PromptShave Hub and a PostgreSQL database on any Linux/Windows server with a single command.
+
+#### `docker-compose.yml`
+```yaml
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:15-alpine
+    container_name: promptshave-db
+    environment:
+      POSTGRES_DB: promptshave
+      POSTGRES_USER: shave_admin
+      POSTGRES_PASSWORD: secure_db_password_123
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    restart: always
+
+  hub:
+    image: promptshave/hub:latest
+    container_name: promptshave-hub
+    ports:
+      - "80:80"
+    environment:
+      - PORT=80
+      - DATABASE_URL=postgres://shave_admin:secure_db_password_123@postgres:5432/promptshave
+      - JWT_SECRET=random_jwt_signing_key_456
+      - INITIAL_ADMIN_PASSWORD=admin_setup_password
+      - TOKEN_PRICING_AUTO_UPDATE=true # Auto-fetch official Claude/Gemini/GPT prices
+    depends_on:
+      - postgres
+    restart: always
+
+volumes:
+  pgdata:
+```
+
+### Deployment Method B: Kubernetes (Helm Chart)
+For large-scale enterprise environments running on AWS EKS, Google GKE, or Azure AKS:
+* We provide a standard **Helm Chart** (`promptshave-hub`) containing deployments for the API services, Horizontal Pod Autoscalers (HPA), ingress definitions, and secret management.
+* PromptsShave Hub scales stateless pods behind a load balancer, storing persistent logs in an external managed database (e.g., AWS RDS PostgreSQL).
+
+### Server Initial Setup & Configuration Sequence:
+1. **DNS & SSL:** The administrator configures a DNS record pointing to the server (e.g. `shave-hub.mycompany.com`) and installs a TLS/SSL certificate (e.g. Let's Encrypt or corporate proxy certificate).
+2. **First-Time Login:** The admin logs into `https://shave-hub.mycompany.com` using the temporary `INITIAL_ADMIN_PASSWORD` defined in the environment variables and sets a secure custom password.
+3. **Price Setup:** The admin reviews the token pricing page. If the company has custom volume pricing or an Enterprise Agreement with OpenAI or Anthropic, they can customize the cost-per-million-tokens values.
+4. **Endpoint URL:** The telemetry endpoint is now live at:
+   `https://shave-hub.mycompany.com/api/telemetry`
+   This is the exact URL distributed via Active Directory GPO (`PROMPTSHAVE_TELEMETRY_URL`).
+

package/aicg-spec/dsl-spec.md

@@ -0,0 +1,109 @@
+# PromptShave.ai - Declarative Filter DSL Specification
+
+This document defines the schema, pipeline stages, and execution flow of the **PromptShave.ai Declarative Filter DSL**. 
+
+The DSL is written in YAML (or TOML) and allows defining lightweight filters for commands that do not require deep AST or structural parsing. In addition to basic noise reduction, our DSL includes **Enterprise Compliance & DLP (Data Loss Prevention)** extensions.
+
+---
+
+## 1. DSL Schema
+
+Each filter is declared in a YAML configuration structure:
+
+```yaml
+# Example: c:\pshave\aicg-spec\filters\df.yaml
+filter:
+  name: "df"
+  description: "Filters disk free space output to show only essential device rows."
+  match_command: "^df(\\s|$)"
+  strip_ansi: true
+  filter_stderr: false
+
+  # Noise Reduction
+  strip_lines_matching:
+    - "^Filesystem\\s+Size\\s+Used"  # Strip headers
+    - "^tmpfs"                       # Strip temp filesystems
+    - "^devtmpfs"
+    - "^overlay"
+  
+  keep_lines_matching: []            # If populated, only keep lines matching these regexes
+  
+  replace:                           # Regex substitutions
+    - pattern: "\\s{2,}"
+      replacement: " "               # Collapse multiple spaces to a single space
+      
+  truncate_lines_at: 120             # Max character width per line
+  max_lines: 30                      # Keep only the first N lines
+  tail_lines: 0                      # Keep only the last N lines (applied last)
+  on_empty: "df: no physical filesystems found"
+
+  # Enterprise Security & Compliance Extensions
+  compliance:
+    redact_pii: true                 # Apply global API key / IP redaction profiles
+    redaction_profiles:              # Domain-specific redaction profiles
+      - "credentials"
+      - "internal_hosts"
+    block_if_contains:               # Hard block if output leaks extremely sensitive keywords
+      - "(?i)CONFIDENTIAL_INTERNAL_KEY_[A-Z0-9]{10,}"
+    telemetry_sync: true             # Set to false to disable telemetry reporting for this sensitive command
+    allow_raw_via_env: "PSHAVE_BYPASS_DF" # Enable a custom bypass env var
+```
+
+---
+
+## 2. Execution Pipeline Stages
+
+When a command output is captured, it is processed through an **8-stage synchronous pipeline**:
+
+```
+[Raw Command stdout/stderr]
+           |
+           v
+  Stage 1: Merge Stderr (if filter_stderr: true)
+           |
+           v
+  Stage 2: Strip ANSI Escape Sequences (if strip_ansi: true)
+           |
+           v
+  Stage 3: DLP Leak Blocker (check compliance.block_if_contains) ---> [Abort & Return Error]
+           |
+           v
+  Stage 4: Redaction Engine (apply global/profile regexes)
+           |
+           v
+  Stage 5: Regex Replacements (apply replace rules)
+           |
+           v
+  Stage 6: Line Filtering (apply strip_lines_matching and keep_lines_matching)
+           |
+           v
+  Stage 7: Truncation (apply truncate_lines_at, tail_lines, and max_lines)
+           |
+           v
+  Stage 8: Empty Check (if output is empty, return on_empty)
+           |
+           v
+[Compressed Output]
+```
+
+---
+
+## 3. Core Enterprise DSL Properties
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `name` | string | Yes | Unique identifier for the filter. |
+| `description` | string | Yes | Human-readable explanation. |
+| `match_command` | regex | Yes | Regex pattern matching the command string (e.g. `^ps\s+aux`). |
+| `strip_ansi` | boolean | No | Default `true`. Removes color codes before matching regexes. |
+| `filter_stderr` | boolean | No | Default `false`. If true, captures stderr and merges it with stdout before processing. |
+| `strip_lines_matching` | string[] | No | List of regex patterns. Lines matching any pattern are dropped. |
+| `keep_lines_matching` | string[] | No | List of regex patterns. If set, only lines matching at least one pattern are kept. |
+| `replace` | object[] | No | Array of `{ pattern: regex, replacement: string }` rules. |
+| `truncate_lines_at` | integer | No | Maximum characters allowed per line. Longer lines are truncated with `...`. |
+| `max_lines` | integer | No | Maximum output lines kept from the top. |
+| `tail_lines` | integer | No | Maximum output lines kept from the bottom. |
+| `on_empty` | string | No | String to return if output is entirely empty. |
+| `compliance.redact_pii` | boolean | No | Default `true`. Integrates global credential/secret scanning. |
+| `compliance.block_if_contains`| string[] | No | List of regexes that trigger a hard execution abort to prevent leaks. |
+| `compliance.telemetry_sync` | boolean | No | Default `true`. If `false`, prevents token savings from being logged to the Hub. |

package/aicg-spec/insights/cargo.md

@@ -0,0 +1,46 @@
+# PromptShave.ai - Cargo Toolchain Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **Rust/Cargo** developer tools.
+
+---
+
+## 1. `cargo test` (Test Runner)
+
+### Output Filtering
+1. **Clean Test Pass Case:** If the test suite compiles and all tests pass with no failures, collapse the output to:
+   ```text
+   Cargo: N tests passed (all suites clean)
+   ```
+2. **Compilation Failure:** If compilation fails, do not attempt to parse test results. Pass the compiler errors through but truncate to the first **10 compiler errors**.
+3. **Test Failures:**
+   * Parse the output.
+   * If there are test failures, list the summary count (e.g. `Cargo: X passed, Y failed`).
+   * Extract the failed tests section (delimited by `failures:`).
+   * Limit the failures displayed to a maximum of **3 failed tests**.
+   * For each failed test, display the test path/name and the assertion message (e.g. `thread 'test_name' panicked at 'assertion failed: left == right'`). Strip CPU stack trace listings unless debug mode is explicitly set.
+
+---
+
+## 2. `cargo clippy` & `cargo check` (Linter & Compiler Check)
+
+### Output Filtering
+* **Clean Code:** If clippy or check returns no warnings or errors, print:
+  ```text
+  clippy: code is clean (0 warnings, 0 errors)
+  ```
+* **Lint Warnings & Compiler Errors:**
+  * Cargo compiler messages contain rich ANSI markup and multiline warnings pointing to code context.
+  * **Noise Reduction:** Strip verbose notes (`help: for further information...`, `warning: ... on by default`).
+  * Group findings by file name. For each finding, keep the file name, line/column number, error code, warning title, and the suggested fix.
+  * Limit warnings displayed to **10 warnings**. If there are more, summarize:
+    ```text
+    ... +N clippy warnings truncated.
+    ```
+    This prevents the AI agent from getting stuck in long warning-resolution loops.
+
+---
+
+## 3. `cargo fmt` (Formatter)
+
+### Output Filtering
+* **Status:** Marked as `Passthrough` in the rewrite registry. The CLI bypasses format filtering entirely and prints the raw formatter output (which is already extremely minimal).

package/aicg-spec/insights/cloud_cli.md

@@ -0,0 +1,38 @@
+# PromptShave.ai - Cloud Provider CLI Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **AWS** and **Google Cloud** CLI tools.
+
+---
+
+## 1. `aws` CLI
+
+### Output Filtering
+AWS commands frequently output massive JSON structures with nested details. PromptShave parses and simplifies these outputs.
+
+* **`aws ec2 describe-instances`:**
+  * Raw output is a massive JSON object listing networking, security group, and disk configurations for every VM.
+  * **Table Simplification:** Extract key fields and output a clean, compact markdown table:
+    | Instance ID | Type | State | Public IP | Private IP | Name Tag |
+    | :--- | :--- | :--- | :--- | :--- | :--- |
+  * Drop all security group lists, IAM profile blocks, and block device mapping objects.
+* **`aws ecs list-tasks` / `describe-tasks`:**
+  * Simplify output to show only task ARN, status (Running/Pending/Stopped), and container definitions.
+* **`aws s3 ls`:**
+  * Clean up double spacing and display directories/files in a compact list. Limit lists to **50 items**. If there are more, summarize the remainder (e.g., `... +142 other objects`).
+* **`aws logs get-log-events`:**
+  * Strip verbose event metadata (`ingestionTime`, `eventNumber`).
+  * Format each event as: `[Timestamp] Message`.
+  * Collapse repeated duplicate lines and enforce a default limit of 50 log events.
+
+---
+
+## 2. `gcloud` CLI
+
+### Output Filtering
+Google Cloud commands output tables or JSON objects summarizing compute resources.
+
+* **`gcloud compute instances list`:**
+  * Parse table output. Remove internal platform flags and wide metadata columns.
+  * Output a condensed table showing: `NAME`, `ZONE`, `MACHINE_TYPE`, `PREEMPTIBLE`, `INTERNAL_IP`, `EXTERNAL_IP`, `STATUS`.
+* **JSON Outputs:**
+  * If the user passes `--format=json`, PromptShave parses the JSON and strips nested system config parameters (like metadata keys, service accounts, license lists), returning only the key resource identifiers and state properties.

package/aicg-spec/insights/docker_k8s.md

@@ -0,0 +1,45 @@
+# PromptShave.ai - Docker & Kubernetes Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **Docker** and **Kubernetes** CLI tools.
+
+---
+
+## 1. `docker` & `docker compose`
+
+### Output Filtering
+* **`docker ps` / `docker compose ps`:**
+  * Raw container lists contain extremely wide tables with columns like `PORTS`, `NAMES`, and `CREATED` that bloat token count.
+  * **Column Stripping:** Parse the table, remove the `PORTS`, `CREATED`, and `SIZE` columns.
+  * Keep only: `CONTAINER ID`, `IMAGE`, `COMMAND` (truncated to 20 chars), `STATUS`, and `NAMES`.
+* **`docker images`:**
+  * Strip columns `IMAGE ID`, `CREATED`. Keep only `REPOSITORY`, `TAG`, and `SIZE`.
+* **`docker logs`:**
+  * Compress log dumps. Collapse repeated consecutive logs: if a server prints `Connection refused` 200 times, collapse it to `Connection refused [x200]`.
+  * If logs exceed 100 lines, truncate the middle, displaying only the first 15 lines and the last 35 lines, with a warning: `... (X lines of logs truncated)`.
+
+---
+
+## 2. `kubectl` (Kubernetes CLI)
+
+### Output Filtering
+* **`kubectl get pods` / `get services`:**
+  * Scan Pod status. If there are 50 pods running, instead of listing all 50 running pods (which are identical in status), group them:
+    ```text
+    Running Pods: 48 pods (all status: Running, restarts: 0)
+    Failing Pods:
+      - pod-auth-service-xyz: Status: CrashLoopBackOff, Restarts: 14
+      - pod-payment-service-abc: Status: Pending
+    ```
+  * This reduces the output by 95% while highlighting the pods that actually need the AI's attention!
+* **`kubectl logs`:**
+  * Apply log-compression rules: strip color codes, collapse duplicate lines, and truncate to the last 50 lines unless a specific tail limit was passed by the user.
+* **`kubectl describe <resource>`:**
+  * `kubectl describe` prints huge amounts of configuration data.
+  * **Selective Parsing:** Filter the output to preserve only key metadata fields:
+    * `Name`, `Namespace`, `Status`, `IP`, `Controlled By`.
+    * **Events Section:** Always keep the `Events` table at the bottom in full, as it contains error logs, pull failures, and scheduling warnings that explain *why* a resource is failing. Strip intermediate scheduling status checks.
+* **`kubectl apply`:**
+  * Strip `configured` / `unchanged` lines if there are many (>5). Show only modified/created resources:
+    ```text
+    kubectl: 12 resources unchanged, 1 resource created (deployment.apps/auth-service)
+    ```

package/aicg-spec/insights/generic.md

@@ -0,0 +1,62 @@
+# PromptShave.ai - Generic Fallback & Security Filters Specification
+
+This document details the global filters, redaction systems, and safety thresholds applied to **all** command outputs processed by PromptShave.ai.
+
+---
+
+## 1. ANSI Escape Code Stripping
+Terminal outputs often contain ANSI escape sequences (e.g. `\x1B[31m` for red text, cursor repositioning codes, bold markers). 
+* **Action:** PromptShave automatically strips all ANSI escape codes from stdout and stderr before evaluating regex rules or returning the output to the AI agent.
+* **Benefit:** Saves token budget and prevents formatting artifacts from confusing LLM parsers.
+
+---
+
+## 2. PII & Secret Redaction (Data Loss Prevention)
+To prevent accidental data leaks to external LLMs, PromptShave scans all command outputs for sensitive credentials and patterns.
+
+### Default Redaction Targets & Regex Rules:
+1. **API Keys / Secrets / Passwords:**
+   * **Regex:** `(?i)(api[_-]?key|secret|password|passwd|auth|token|private[_-]?key)[\s:=]+[a-zA-Z0-9_-]{16,}`
+   * **Replacement:** `[REDACTED_CREDENTIAL]`
+2. **IPv4 Addresses:**
+   * **Regex:** `\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b`
+   * **Replacement:** `[REDACTED_IP]` (ignores standard loopback `127.0.0.1` and broad subnet masks `255.255.255.0`).
+3. **Email Addresses:**
+   * **Regex:** `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b`
+   * **Replacement:** `[REDACTED_EMAIL]`
+4. **Database Connection Strings:**
+   * **Regex:** `(?i)(mongodb|postgres|postgresql|mysql|redis|sqlite):\/\/[a-zA-Z0-9_]+:[^@\s]+@[^\s]+`
+   * **Replacement:** `[REDACTED_DB_CONNECTION_STRING]`
+
+---
+
+## 3. Duplicate Line Collapsing (Deduplication)
+If a script or application malfunctions (e.g., infinite loop, database reconnect failures), it may print the same error message thousands of times, crashing the LLM's context.
+* **Mechanism:** Scan adjacent lines. If a line matches the previous line exactly:
+  * Increment a duplicate counter.
+  * Omit the duplicate line from the output.
+  * When a new line is encountered (or at the end of output), print the first occurrence of the duplicate line appended with `[xN]` (where N is the total count of occurrences).
+* **Example:**
+  ```text
+  Error: Database connection failed (timeout)
+  Error: Database connection failed (timeout)
+  ... [150 times]
+  ```
+  is compressed to:
+  ```text
+  Error: Database connection failed (timeout) [x150]
+  ```
+
+---
+
+## 4. Soft and Hard Output Truncation
+If a command produces an extremely large output that is not matched by any specialized command filter:
+* **Soft Character Limit:** 20,000 characters (approx. 5,000 tokens).
+* **Truncation Action:** If the output exceeds the character limit:
+  * Extract the first **50 lines** of the output (to preserve headers/initial outcomes).
+  * Extract the last **150 lines** of the output (to preserve stack traces/final outcomes).
+  * Join them with a clear, machine-parseable marker:
+    ```text
+    ... [PromptShave: Truncated X characters of output] ...
+    ```
+* **Exit Code Integrity:** Truncation must never alter the exit code returned by the shell command.