@intentsolutionsio/freshie-inventory-manager 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "freshie-inventory-manager",
+  "version": "1.0.0",
+  "description": "Unified command center for the freshie ecosystem inventory database — discovery scans, compliance grading, batch remediation, querying, and reporting across 50 tables of plugin/skill/pack metadata",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "repository": "https://github.com/jeremylongshore/claude-code-plugins",
+  "license": "MIT",
+  "keywords": [
+    "database",
+    "inventory",
+    "freshie",
+    "compliance",
+    "sqlite",
+    "ecosystem",
+    "audit",
+    "agent-skills"
+  ]
+}

package/README.md

@@ -0,0 +1,47 @@
+# Freshie Inventory Manager
+
+Unified command center for the freshie ecosystem inventory database. Manages discovery scans, compliance validation, batch remediation, ad-hoc queries, and status reporting across the full plugin/skill/pack lifecycle.
+
+## Installation
+
+```bash
+/plugin marketplace add jeremylongshore/claude-code-plugins
+```
+
+## Usage
+
+Invoke with natural language:
+
+- `freshie status` — dashboard with run counts, grades, staleness
+- `run a discovery scan` — trigger rebuild-inventory.py
+- `compliance check` — validate and populate DB with enterprise grading
+- `remediate skills` — batch fix compliance issues
+- `query freshie for stub skills` — ad-hoc SQLite queries
+- `freshie report` — generate a status update summary
+- `compare discovery runs` — delta analysis between runs
+- `show pack coverage` — SaaS pack completeness metrics
+- `find anomalies` — detect data quality issues
+- `export grades to CSV` — export compliance data
+
+## Features
+
+- Pre-loaded DB status via dynamic context injection
+- 10 distinct operations with automatic intent detection
+- Pre-built query library for common investigations
+- Delta reporting between discovery runs
+- Dry-run-first remediation safety pattern
+
+## Requirements
+
+- `sqlite3` CLI
+- `python3` with `pyyaml`
+- Freshie database at `freshie/inventory.sqlite`
+
+## Files
+
+- `skills/freshie-inventory/SKILL.md` — Main skill definition
+- `skills/freshie-inventory/references/common-queries.md` — Pre-built SQLite query library
+
+## License
+
+MIT

package/agents/anomaly-detector.md

@@ -0,0 +1,113 @@
+---
+name: anomaly-detector
+description: "Detect data quality issues, stubs, orphan plugins, and outliers in the freshie inventory database"
+model: inherit
+---
+
+You are a freshie anomaly detector. Your job is to identify data quality issues,
+suspicious patterns, and outliers in the ecosystem inventory database.
+
+## Process
+
+Run these checks against the latest discovery run and group findings by severity.
+
+### Check 1: Stored Anomalies
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT * FROM anomalies
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  ORDER BY rowid;
+"
+```
+
+### Check 2: Low Word Count Skills (Likely Stubs)
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT cs.skill_path, cs.word_count, sc.grade, sc.is_stub
+  FROM content_signals cs
+  JOIN skill_compliance sc ON cs.skill_path = sc.skill_path AND cs.run_id = sc.run_id
+  WHERE cs.run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND cs.word_count < 50
+  ORDER BY cs.word_count ASC LIMIT 20;
+"
+```
+
+### Check 3: Plugins with No Skills
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT p.name, p.category
+  FROM plugins p
+  LEFT JOIN skills s ON p.path = s.plugin_path AND p.run_id = s.run_id
+  WHERE p.run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND s.name IS NULL
+  ORDER BY p.category, p.name;
+"
+```
+
+### Check 4: High Template-Text Density
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT cs.skill_path, cs.placeholder_density, cs.word_count, sc.grade
+  FROM content_signals cs
+  JOIN skill_compliance sc ON cs.skill_path = sc.skill_path AND cs.run_id = sc.run_id
+  WHERE cs.run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND cs.placeholder_density > 0.1
+  ORDER BY cs.placeholder_density DESC LIMIT 15;
+"
+```
+
+### Check 5: Duplicate Files
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT filename, COUNT(*) as occurrences
+  FROM duplicate_files
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  GROUP BY filename
+  HAVING COUNT(*) > 1
+  ORDER BY occurrences DESC LIMIT 15;
+"
+```
+
+### Check 6: Score Outliers (> 2 std dev from mean)
+
+```bash
+sqlite3 freshie/inventory.sqlite "
+  WITH stats AS (
+    SELECT AVG(score) as avg_score, AVG(score*score) - AVG(score)*AVG(score) as variance
+    FROM skill_compliance WHERE run_id=(SELECT MAX(id) FROM discovery_runs)
+  )
+  SELECT sc.skill_path, sc.score, sc.grade
+  FROM skill_compliance sc, stats
+  WHERE sc.run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND ABS(sc.score - stats.avg_score) > 2 * SQRT(stats.variance)
+  ORDER BY sc.score ASC LIMIT 20;
+"
+```
+
+## Output Format
+
+```
+ANOMALY SCAN RESULTS
+======================
+
+CRITICAL:
+  - {finding} ({count} affected)
+
+WARNING:
+  - {finding} ({count} affected)
+
+INFO:
+  - {finding} ({count} affected)
+
+Total: {n} findings across {categories} categories
+```
+
+Categorize by severity:
+- **CRITICAL**: Plugins with no skills, D/F grades, missing DB tables
+- **WARNING**: Stubs, high template density, score outliers
+- **INFO**: Duplicates, minor data quality notes

package/agents/compliance-validator.md

@@ -0,0 +1,79 @@
+---
+name: compliance-validator
+description: "Run enterprise compliance validation against the freshie DB and produce grade summary with worst offenders"
+model: inherit
+---
+
+You are a freshie compliance validator. Your job is to run the enterprise-tier validation
+pipeline, populate the freshie database with results, and produce a structured summary.
+
+## Process
+
+1. **Run the validator** with enterprise grading and DB population:
+```bash
+python3 scripts/validate-skills-schema.py --enterprise --populate-db freshie/inventory.sqlite --verbose
+```
+
+2. **Summarize grade distribution** with percentages:
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT grade, COUNT(*) as count,
+    ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM skill_compliance
+      WHERE run_id=(SELECT MAX(id) FROM discovery_runs)), 1) as pct
+  FROM skill_compliance
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  GROUP BY grade ORDER BY grade;
+"
+```
+
+3. **Calculate average score**:
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT ROUND(AVG(score), 1) as avg_score
+  FROM skill_compliance
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs);
+"
+```
+
+4. **List worst offenders** (D and F grades):
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT skill_path, score, grade, error_count, warning_count
+  FROM skill_compliance
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND grade IN ('D', 'F')
+  ORDER BY score ASC LIMIT 15;
+"
+```
+
+5. **Count upgrade candidates** (B grade, score 85-89):
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT COUNT(*) as upgrade_candidates
+  FROM skill_compliance
+  WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+    AND score BETWEEN 85 AND 89;
+"
+```
+
+## Output Format
+
+```
+COMPLIANCE VALIDATION COMPLETE
+================================
+Grade Distribution:
+  A: {n} ({pct}%) | B: {n} ({pct}%) | C: {n} ({pct}%) | D: {n} ({pct}%) | F: {n} ({pct}%)
+
+Average Score: {avg}/100
+Upgrade Candidates (B, 85-89): {n}
+
+Worst Offenders:
+  {path} — {score} ({grade}) [{errors} errors, {warnings} warnings]
+  ...
+```
+
+## Error Handling
+
+- If validator fails, report error output and suggest `pip install pyyaml`
+- If DB is empty, recommend running a discovery scan first
+- Validator may produce warnings — include notable ones in the summary

package/agents/discovery-scanner.md

@@ -0,0 +1,57 @@
+---
+name: discovery-scanner
+description: "Run freshie discovery scans — full repo scan via rebuild-inventory.py with delta reporting against previous run"
+model: inherit
+---
+
+You are a freshie ecosystem scanner. Your job is to run a full discovery scan of the
+claude-code-plugins repository and report what changed.
+
+## Process
+
+1. **Show current state** before scanning:
+```bash
+sqlite3 freshie/inventory.sqlite "SELECT id, run_date, total_plugins, total_skills, COALESCE(total_packs, 0) as total_packs FROM discovery_runs ORDER BY id DESC LIMIT 1;"
+```
+
+2. **Run the scan**:
+```bash
+python3 freshie/scripts/rebuild-inventory.py
+```
+
+3. **Report the delta** — compare new run vs previous:
+```bash
+sqlite3 freshie/inventory.sqlite "
+  SELECT
+    d1.id as new_run, d1.total_plugins as new_plugins, d1.total_skills as new_skills,
+    COALESCE(d1.total_packs, 0) as new_packs,
+    d2.id as old_run, d2.total_plugins as old_plugins, d2.total_skills as old_skills,
+    COALESCE(d2.total_packs, 0) as old_packs,
+    d1.total_plugins - d2.total_plugins as plugin_delta,
+    d1.total_skills - d2.total_skills as skill_delta
+  FROM discovery_runs d1
+  JOIN discovery_runs d2 ON d2.id = d1.id - 1
+  ORDER BY d1.id DESC LIMIT 1;
+"
+```
+
+## Output Format
+
+```
+DISCOVERY SCAN COMPLETE
+========================
+New Run:  #{id} ({date})
+Previous: #{id} ({date})
+
+Plugins: {old} → {new} ({+/-delta})
+Skills:  {old} → {new} ({+/-delta})
+Packs:   {old} → {new} ({+/-delta})
+
+Scan duration: {time}
+```
+
+## Error Handling
+
+- If `rebuild-inventory.py` fails, report the error output verbatim
+- If this is the first run (no previous), just report absolute counts
+- If DB doesn't exist, the script will create it

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@intentsolutionsio/freshie-inventory-manager",
+  "version": "1.0.0",
+  "description": "Unified command center for the freshie ecosystem inventory database — discovery scans, compliance grading, batch remediation, querying, and reporting across 50 tables of plugin/skill/pack metadata",
+  "keywords": [
+    "database",
+    "inventory",
+    "freshie",
+    "compliance",
+    "sqlite",
+    "ecosystem",
+    "audit",
+    "agent-skills",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/database/freshie-inventory-manager"
+  },
+  "homepage": "https://tonsofskills.com/plugins/freshie-inventory-manager",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install freshie-inventory-manager\\\\n  or /plugin install freshie-inventory-manager@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/freshie-inventory/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: freshie-inventory
+description: |
+  Manage the freshie ecosystem inventory database — a CMDB tracking all plugins,
+  skills, packs, and compliance grades across 50 SQLite tables. Use when checking
+  ecosystem health, running discovery scans, validating compliance, remediating
+  issues, querying inventory data, comparing runs, exporting data, or generating
+  status reports. Trigger with "freshie status", "inventory scan", "ecosystem audit",
+  "grade report", "compliance check", "remediate skills", "query freshie",
+  "compare runs", "export grades", or "freshie report".
+allowed-tools: Read, Write, Edit, Bash(sqlite3:*), Bash(python3:*), Bash(node:*), Bash(mkdir:*), Bash(wc:*), Glob, Grep, AskUserQuestion, Skill, Agent
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [database, inventory, freshie, compliance, ecosystem, sqlite]
+---
+
+# Freshie Inventory Manager
+
+Interactive command center for the freshie ecosystem inventory database.
+
+## Current DB Status
+
+!`sqlite3 freshie/inventory.sqlite "SELECT 'Run #' || id || ' — ' || run_date || ' | Plugins: ' || total_plugins || ' | Skills: ' || total_skills || ' | Packs: ' || COALESCE(total_packs, 0) FROM discovery_runs ORDER BY id DESC LIMIT 3;" 2>/dev/null || echo "DB not found at freshie/inventory.sqlite"`
+
+!`sqlite3 freshie/inventory.sqlite "SELECT grade || ': ' || COUNT(*) FROM skill_compliance GROUP BY grade ORDER BY grade;" 2>/dev/null`
+
+## Overview
+
+The freshie database is the single source of truth for ecosystem-wide metrics — plugin counts,
+skill compliance grades, pack coverage, anomaly detection, and historical trends across versioned
+discovery runs. This skill is an **interactive wizard** — it always asks what you want to do,
+then delegates heavy operations to specialized subagents.
+
+**Database location:** `freshie/inventory.sqlite` (50 tables, versioned by `run_id`)
+
+**Key scripts:**
+- `freshie/scripts/rebuild-inventory.py` — full repo scan, creates new discovery run
+- `freshie/scripts/batch-remediate.py` — auto-fix compliance issues
+- `scripts/validate-skills-schema.py` — enterprise validation with DB population
+
+## Prerequisites
+
+- `sqlite3` CLI available on PATH
+- `python3` with `pyyaml` installed
+- Working directory is the repo root (`claude-code-plugins/`)
+- Database exists at `freshie/inventory.sqlite`
+- `/email` skill installed (for PDF report emailing)
+
+## Instructions
+
+### Step 1: Present Main Menu
+
+When invoked, ALWAYS start by presenting this menu using AskUserQuestion:
+
+```
+FRESHIE INVENTORY COMMAND CENTER
+================================================================
+
+What would you like to do?
+
+ 1. Dashboard        — Current status, grades, staleness
+ 2. Discovery Scan   — Full repo scan, create new run
+ 3. Compliance Check — Enterprise validation + DB population
+ 4. Remediation      — Batch fix compliance issues
+ 5. Query            — Ad-hoc SQLite queries
+ 6. Compare Runs     — Delta analysis between runs
+ 7. Export Data      — CSV exports to freshie/exports/
+ 8. Anomaly Scan     — Data quality + outlier detection
+ 9. Pack Coverage    — SaaS pack completeness metrics
+10. Full Audit       — Scan + validate + report (end-to-end)
+11. Report Only      — Generate summary from existing data
+```
+
+Use AskUserQuestion with these options. If the user's initial prompt already contains
+a clear intent (e.g., "freshie status"), skip the menu and route directly.
+
+### Step 2: Execute Chosen Workflow
+
+Based on selection, follow the matching workflow below. Every workflow ends with
+Step 3 (Email Report).
+
+---
+
+## Workflow A: Dashboard
+
+Run these queries and present as a formatted dashboard:
+
+```bash
+sqlite3 freshie/inventory.sqlite "SELECT id, run_date, total_plugins, total_skills, COALESCE(total_packs,0) FROM discovery_runs ORDER BY id DESC LIMIT 1;"
+sqlite3 freshie/inventory.sqlite "SELECT grade, COUNT(*) FROM skill_compliance WHERE run_id=(SELECT MAX(id) FROM discovery_runs) GROUP BY grade ORDER BY grade;"
+sqlite3 freshie/inventory.sqlite "SELECT CAST(julianday('now') - julianday(run_date) AS INTEGER) FROM discovery_runs ORDER BY id DESC LIMIT 1;"
+sqlite3 freshie/inventory.sqlite "SELECT 'plugins', COUNT(*) FROM plugins WHERE run_id=(SELECT MAX(id) FROM discovery_runs) UNION ALL SELECT 'skills', COUNT(*) FROM skills WHERE run_id=(SELECT MAX(id) FROM discovery_runs) UNION ALL SELECT 'packs', COUNT(*) FROM packs WHERE run_id=(SELECT MAX(id) FROM discovery_runs) UNION ALL SELECT 'anomalies', COUNT(*) FROM anomalies WHERE run_id=(SELECT MAX(id) FROM discovery_runs);"
+# Core vs SaaS pack breakdown
+sqlite3 freshie/inventory.sqlite "SELECT CASE WHEN path LIKE '%saas-packs%' THEN 'saas-pack-skills' ELSE 'core-skills' END as type, COUNT(*) FROM skills WHERE run_id=(SELECT MAX(id) FROM discovery_runs) GROUP BY type;"
+```
+
+Present as:
+```
+FRESHIE INVENTORY DASHBOARD
+============================
+Last Scan:     Run #{id} — {date} ({days} days ago)
+Plugins:       {n}
+Skills:        {n} total
+  Core:        {n} (hand-crafted plugin skills)
+  SaaS Packs:  {n} (auto-generated pack skills)
+Packs:         {n}
+
+Grade Distribution:
+  A: {n}  B: {n}  C: {n}  D: {n}  F: {n}
+
+Staleness: {Fresh (<3d) | Stale (3-7d) | CRITICAL (>7d)}
+```
+
+If Critical (>7 days), recommend a discovery scan.
+
+---
+
+## Workflow B: Discovery Scan
+
+**Delegate to the discovery-scanner subagent** via the Agent tool:
+
+```
+Launch Agent: discovery-scanner
+Prompt: "Run a full freshie discovery scan. Show current state first, execute
+rebuild-inventory.py, then report the delta (plugin/skill count changes)
+compared to the previous run."
+```
+
+The subagent handles the long-running scan in isolation and returns the delta report.
+
+---
+
+## Workflow C: Compliance Check
+
+**Delegate to the compliance-validator subagent** via the Agent tool:
+
+```
+Launch Agent: compliance-validator
+Prompt: "Run enterprise compliance validation against the freshie DB.
+Execute: python3 scripts/validate-skills-schema.py --enterprise --populate-db freshie/inventory.sqlite --verbose
+Then summarize: grade distribution with percentages, and list all D/F grade skills."
+```
+
+The subagent runs the full validation pipeline and returns a structured summary.
+
+---
+
+## Workflow D: Remediation
+
+**CRITICAL: Always dry-run first, then confirm before executing.**
+
+1. Run dry-run:
+```bash
+python3 freshie/scripts/batch-remediate.py --dry-run
+```
+
+2. Present the changes that would be made.
+
+3. Use AskUserQuestion:
+```
+REMEDIATION PREVIEW
+================================================================
+{summary of proposed changes}
+
+Proceed?
+  - Execute — Apply all fixes
+  - Cancel  — Abort, no changes made
+```
+
+4. Only if user selects "Execute":
+```bash
+python3 freshie/scripts/batch-remediate.py --all --execute
+```
+
+5. After execution, run Workflow C (Compliance Check) to measure improvement.
+
+---
+
+## Workflow E: Query
+
+For ad-hoc queries, load the pre-built query library from [common-queries.md](references/common-queries.md).
+
+Match the user's question to the closest pre-built query. If no match, construct a custom
+query against the freshie schema using these key tables:
+
+| Table | Contents |
+|-------|----------|
+| `plugins` | name, category, version, path |
+| `skills` | name, plugin_path, has_references, has_scripts |
+| `packs` | name, skill_count, category |
+| `skill_compliance` | score, grade, error_count, warning_count, is_stub |
+| `plugin_compliance` | plugin-level roll-up scores |
+| `content_signals` | word_count, code_block_count |
+| `anomalies` | detected data quality issues |
+| `discovery_runs` | run history with timestamps |
+
+Always filter to latest run: `WHERE run_id = (SELECT MAX(id) FROM discovery_runs)`
+
+After showing results, use AskUserQuestion to offer follow-up:
+```
+Results shown. What next?
+  - Refine query  — Modify or drill deeper
+  - Export to CSV — Save results to file
+  - Back to menu  — Return to main menu
+```
+
+---
+
+## Workflow F: Compare Runs
+
+```bash
+sqlite3 freshie/inventory.sqlite "SELECT id, run_date, total_plugins, total_skills, COALESCE(total_packs,0) FROM discovery_runs ORDER BY id;"
+```
+
+If more than 2 runs exist, use AskUserQuestion to let user pick which two to compare.
+Default to the two most recent.
+
+Use the "Historical Trends" queries from [common-queries.md](references/common-queries.md) for:
+- Grade distribution comparison between runs
+- Skills that changed grade (upgrades/downgrades with score delta)
+- New skills added since previous run
+- Skills removed since previous run
+
+---
+
+## Workflow G: Export Data
+
+```bash
+mkdir -p freshie/exports
+```
+
+Use AskUserQuestion to let user pick what to export:
+```
+EXPORT OPTIONS
+================================================================
+What should I export?
+
+  - Skill Grades    — All skill compliance scores + grades
+  - Plugin Inventory — All plugins with category and version
+  - Pack Coverage   — Pack names, skill counts, categories
+  - Full Dump       — All three exports
+  - Custom Query    — Export any query result to CSV
+```
+
+Then run the appropriate export:
+```bash
+sqlite3 -header -csv freshie/inventory.sqlite "{query}" > freshie/exports/{filename}.csv
+```
+
+Report file paths and row counts.
+
+---
+
+## Workflow H: Anomaly Scan
+
+**Delegate to the anomaly-detector subagent** via the Agent tool:
+
+```
+Launch Agent: anomaly-detector
+Prompt: "Run anomaly detection on the freshie inventory DB. Check:
+1. Stored anomalies from the latest discovery run
+2. Skills with word count < 50 (likely stubs)
+3. Plugins with no skills
+4. Skills with high template-text density (>10%)
+5. Duplicate files
+Report all findings grouped by severity."
+```
+
+---
+
+## Workflow I: Pack Coverage
+
+```bash
+sqlite3 freshie/inventory.sqlite "SELECT name, skill_count, category FROM packs WHERE run_id=(SELECT MAX(id) FROM discovery_runs) ORDER BY skill_count DESC;"
+```
+
+Also flag packs below minimum viable (< 3 skills) and show grade distribution within packs.
+Use pack coverage queries from [common-queries.md](references/common-queries.md).
+
+---
+
+## Workflow J: Full Audit
+
+This is the power workflow — runs everything end-to-end:
+
+1. **Discovery Scan** (Workflow B) — via subagent
+2. **Compliance Check** (Workflow C) — via subagent
+3. **Anomaly Scan** (Workflow H) — via subagent
+4. **Report Generation** (Workflow K) — compile all results
+
+Launch steps 1-3 as parallel subagents, then compile the report when all complete.
+
+---
+
+## Workflow K: Report Only
+
+Generate a summary report from existing data (no new scans). Gather dashboard data
+(Workflow A queries) and compile:
+
+```
+FRESHIE ECOSYSTEM REPORT — {date}
+================================================================
+
+Discovery: Run #{id} ({date})
+  Plugins: {n} | Skills: {n} | Packs: {n}
+
+Compliance (enterprise tier):
+  A: {n} ({pct}%) | B: {n} ({pct}%) | C: {n} ({pct}%) | D: {n} ({pct}%)
+
+  Average score: {avg}/100
+
+Since last run:
+  Plugins: {+/-delta} | Skills: {+/-delta}
+  Grade upgrades: {n} | Downgrades: {n}
+
+Top Issues:
+  1. {issue}
+  2. {issue}
+  3. {issue}
+
+Recommendations:
+  - {action}
+  - {action}
+================================================================
+```
+
+---
+
+### Step 3: Email PDF Report
+
+After ANY workflow completes, use AskUserQuestion to offer the report:
+
+```
+WORKFLOW COMPLETE
+================================================================
+{Brief summary of what was done}
+
+Would you like a PDF report emailed?
+  - Yes, email me      — Generate PDF + send to jeremy@intentsolutions.io
+  - Yes, email someone — Specify recipient
+  - Save PDF only      — Generate PDF, no email
+  - No thanks          — Done
+```
+
+If the user wants a report:
+
+1. **Generate markdown report** — write the workflow results to `/tmp/freshie-report-{date}.md`
+2. **Convert to PDF** using the email skill's converter:
+```bash
+python3 ~/.claude/skills/email/scripts/md-to-pdf.py /tmp/freshie-report-{date}.md /tmp/freshie-report-{date}.pdf --style professional
+```
+3. **Send via /email skill** — invoke the Skill tool with `skill: "email"` and args describing:
+   - To: recipient (default: jeremy@intentsolutions.io)
+   - Subject: "Freshie Ecosystem Report — {date}"
+   - Body: brief summary
+   - Attachment: the generated PDF
+
+## Output
+
+All operations produce structured text output. Dashboards use fixed-width formatting.
+Query results use table format. Deltas show +/- indicators. CSV exports write to
+`freshie/exports/`. PDF reports write to `/tmp/` and optionally email.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "DB not found" | Missing `freshie/inventory.sqlite` | Run `python3 freshie/scripts/rebuild-inventory.py` to create |
+| "no such table" | DB schema outdated or empty | Run a fresh discovery scan (Workflow B) |
+| Empty grades | Compliance not yet populated | Run compliance validation (Workflow C) |
+| `rebuild-inventory.py` fails | Missing `pyyaml` | `pip install pyyaml` |
+| Stale data (>7 days) | No recent scans | Run discovery scan, then compliance |
+| PDF generation fails | Missing `weasyprint` | `pip install weasyprint` |
+| Email send fails | Missing env vars | Check `~/.env` for GMAIL_APP_PASSWORD |
+
+## Examples
+
+See [examples.md](references/examples.md) for detailed input/output examples covering all workflows:
+- Quick status check (direct intent, skips menu)
+- Full audit with email PDF report (parallel subagents)
+- Ad-hoc query with CSV export follow-up
+- Remediation cycle (dry-run, confirm, re-validate)
+- Compare discovery runs (delta analysis)
+- Pack coverage analysis
+
+## Resources
+
+- [Common Queries](references/common-queries.md) — pre-built SQLite query library: grades, stubs, plugins, packs, content quality, trends, anomalies, field analysis, cross-references
+- `freshie/scripts/rebuild-inventory.py` — full repo scanner, versioned discovery runs
+- `freshie/scripts/batch-remediate.py` — compliance fix engine (`--dry-run`, `--all --execute`)
+- `scripts/validate-skills-schema.py` — universal validator (`--enterprise --populate-db`)
+- `freshie/inventory.sqlite` — the database (50 tables, versioned by `run_id`)
+- `~/.claude/skills/email/scripts/md-to-pdf.py` — markdown to PDF converter
+- `/email` skill — email sending with attachments

package/skills/freshie-inventory/references/common-queries.md

@@ -0,0 +1,349 @@
+# Common Freshie Queries
+
+Pre-built SQLite queries for the freshie inventory database. All queries filter to the latest
+discovery run unless comparing across runs.
+
+## Table of Contents
+
+- [Grade & Compliance](#grade--compliance)
+- [Stub Detection](#stub-detection)
+- [Plugin Analysis](#plugin-analysis)
+- [Pack Coverage](#pack-coverage)
+- [Content Quality](#content-quality)
+- [Historical Trends](#historical-trends)
+- [Anomalies & Data Quality](#anomalies--data-quality)
+- [Field Analysis](#field-analysis)
+- [Cross-References](#cross-references)
+
+## Grade & Compliance
+
+### Grade Distribution (Latest Run)
+
+```sql
+SELECT grade, COUNT(*) as count,
+  ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM skill_compliance WHERE run_id=(SELECT MAX(id) FROM discovery_runs)), 1) as pct
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY grade ORDER BY grade;
+```
+
+### Average Score by Category
+
+```sql
+SELECT p.category, ROUND(AVG(sc.score), 1) as avg_score, COUNT(*) as skill_count
+FROM skill_compliance sc
+JOIN skills s ON sc.skill_path = s.path AND sc.run_id = s.run_id
+JOIN plugins p ON s.plugin_path = p.path AND s.run_id = p.run_id
+WHERE sc.run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY p.category
+ORDER BY avg_score DESC;
+```
+
+### Low-Grade Skills (D and F)
+
+```sql
+SELECT skill_path, score, grade, error_count, warning_count, missing_fields
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND grade IN ('D', 'F')
+ORDER BY score ASC;
+```
+
+### Skills Just Below A Grade (Upgrade Candidates)
+
+```sql
+SELECT skill_path, score, grade, missing_fields
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND score BETWEEN 80 AND 89
+ORDER BY score DESC;
+```
+
+### Skills with Most Errors
+
+```sql
+SELECT skill_path, error_count, warning_count, score, grade
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND error_count > 0
+ORDER BY error_count DESC LIMIT 20;
+```
+
+## Stub Detection
+
+### All Stub Skills
+
+```sql
+SELECT skill_path, score, grade, stub_reasons
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND is_stub = 1
+ORDER BY skill_path;
+```
+
+### Stub Rate by Category
+
+```sql
+SELECT p.category,
+  COUNT(*) as total,
+  SUM(sc.is_stub) as stubs,
+  ROUND(SUM(sc.is_stub) * 100.0 / COUNT(*), 1) as stub_pct
+FROM skill_compliance sc
+JOIN skills s ON sc.skill_path = s.path AND sc.run_id = s.run_id
+JOIN plugins p ON s.plugin_path = p.path AND s.run_id = p.run_id
+WHERE sc.run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY p.category
+ORDER BY stub_pct DESC;
+```
+
+### Non-Stub Skills Scoring Below 70
+
+```sql
+SELECT skill_path, score, grade, error_count
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND is_stub = 0 AND score < 70
+ORDER BY score ASC;
+```
+
+## Plugin Analysis
+
+### Plugin Count by Category
+
+```sql
+SELECT category, COUNT(*) as count
+FROM plugins
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY category
+ORDER BY count DESC;
+```
+
+### Plugins Missing Required Companions
+
+```sql
+SELECT p.name, p.category,
+  GROUP_CONCAT(pc.companion_type) as missing
+FROM plugins p
+LEFT JOIN plugin_companions pc ON p.path = pc.plugin_path AND p.run_id = pc.run_id
+WHERE p.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND pc.exists = 0
+GROUP BY p.name
+ORDER BY p.category, p.name;
+```
+
+### Plugin Compliance Roll-Up
+
+```sql
+SELECT p.name, p.category, pc.score, pc.grade
+FROM plugin_compliance pc
+JOIN plugins p ON pc.plugin_path = p.path AND pc.run_id = p.run_id
+WHERE pc.run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY pc.score ASC LIMIT 20;
+```
+
+### Plugins with No Skills
+
+```sql
+SELECT p.name, p.category, p.path
+FROM plugins p
+LEFT JOIN skills s ON p.path = s.plugin_path AND p.run_id = s.run_id
+WHERE p.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND s.name IS NULL
+ORDER BY p.category, p.name;
+```
+
+## Pack Coverage
+
+### Pack Skill Counts
+
+```sql
+SELECT name, skill_count, category
+FROM packs
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY skill_count DESC;
+```
+
+### Packs Below Minimum Viable (< 3 Skills)
+
+```sql
+SELECT name, skill_count
+FROM packs
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND skill_count < 3
+ORDER BY skill_count ASC;
+```
+
+### Pack Aggregate Metrics
+
+```sql
+SELECT pa.pack_name, pa.total_skills, pa.avg_score, pa.min_score, pa.max_score
+FROM pack_aggregates pa
+WHERE pa.run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY pa.avg_score ASC;
+```
+
+## Content Quality
+
+### Lowest Word Count Skills
+
+```sql
+SELECT cs.skill_path, cs.word_count, sc.grade, sc.is_stub
+FROM content_signals cs
+JOIN skill_compliance sc ON cs.skill_path = sc.skill_path AND cs.run_id = sc.run_id
+WHERE cs.run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY cs.word_count ASC LIMIT 20;
+```
+
+### High Placeholder Density (Likely Templated)
+
+```sql
+SELECT cs.skill_path, cs.placeholder_density, cs.word_count, sc.grade
+FROM content_signals cs
+JOIN skill_compliance sc ON cs.skill_path = sc.skill_path AND cs.run_id = sc.run_id
+WHERE cs.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND cs.placeholder_density > 0.1
+ORDER BY cs.placeholder_density DESC LIMIT 20;
+```
+
+### Skills with Most Code Blocks
+
+```sql
+SELECT cs.skill_path, cs.code_block_count, cs.word_count, sc.grade
+FROM content_signals cs
+JOIN skill_compliance sc ON cs.skill_path = sc.skill_path AND cs.run_id = sc.run_id
+WHERE cs.run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY cs.code_block_count DESC LIMIT 20;
+```
+
+## Historical Trends
+
+### All Discovery Runs
+
+```sql
+SELECT id, run_date, commit_hash, total_plugins, total_skills, total_packs, total_files
+FROM discovery_runs ORDER BY id;
+```
+
+### Grade Trend Across Runs
+
+```sql
+SELECT sc.run_id, sc.grade, COUNT(*) as count
+FROM skill_compliance sc
+GROUP BY sc.run_id, sc.grade
+ORDER BY sc.run_id, sc.grade;
+```
+
+### Skills That Changed Grade Between Runs
+
+```sql
+SELECT old.skill_path,
+  old.grade as old_grade, old.score as old_score,
+  new.grade as new_grade, new.score as new_score,
+  new.score - old.score as delta
+FROM skill_compliance old
+JOIN skill_compliance new ON old.skill_path = new.skill_path
+WHERE old.run_id = (SELECT MAX(id) - 1 FROM discovery_runs)
+  AND new.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND old.grade != new.grade
+ORDER BY delta DESC;
+```
+
+### New Skills Since Previous Run
+
+```sql
+SELECT new.skill_path, new.grade, new.score
+FROM skill_compliance new
+LEFT JOIN skill_compliance old ON new.skill_path = old.skill_path
+  AND old.run_id = (SELECT MAX(id) - 1 FROM discovery_runs)
+WHERE new.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND old.skill_path IS NULL
+ORDER BY new.score DESC;
+```
+
+### Removed Skills Since Previous Run
+
+```sql
+SELECT old.skill_path, old.grade, old.score
+FROM skill_compliance old
+LEFT JOIN skill_compliance new ON old.skill_path = new.skill_path
+  AND new.run_id = (SELECT MAX(id) FROM discovery_runs)
+WHERE old.run_id = (SELECT MAX(id) - 1 FROM discovery_runs)
+  AND new.skill_path IS NULL
+ORDER BY old.skill_path;
+```
+
+## Anomalies & Data Quality
+
+### All Anomalies (Latest Run)
+
+```sql
+SELECT * FROM anomalies
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY rowid;
+```
+
+### Duplicate File Detection
+
+```sql
+SELECT filename, COUNT(*) as occurrences
+FROM duplicate_files
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY filename
+HAVING COUNT(*) > 1
+ORDER BY occurrences DESC LIMIT 20;
+```
+
+### Skills with References Directory
+
+```sql
+SELECT skill_path, has_references_dir, has_scripts_dir, has_examples
+FROM skill_compliance
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND has_references_dir = 1
+ORDER BY skill_path;
+```
+
+## Field Analysis
+
+### Most Common Frontmatter Fields
+
+```sql
+SELECT field_name, COUNT(*) as usage_count
+FROM frontmatter_fields
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY field_name
+ORDER BY usage_count DESC;
+```
+
+### Agent Compliance Issues
+
+```sql
+SELECT ac.agent_path, ac.invalid_fields, ac.missing_fields
+FROM agent_compliance ac
+WHERE ac.run_id = (SELECT MAX(id) FROM discovery_runs)
+  AND (ac.invalid_fields IS NOT NULL OR ac.missing_fields IS NOT NULL)
+ORDER BY ac.agent_path;
+```
+
+## Cross-References
+
+### Skill-to-Plugin Mapping
+
+```sql
+SELECT s.name as skill, p.name as plugin, p.category, sc.grade
+FROM skills s
+JOIN plugins p ON s.plugin_path = p.path AND s.run_id = p.run_id
+JOIN skill_compliance sc ON sc.skill_path = s.path AND sc.run_id = s.run_id
+WHERE s.run_id = (SELECT MAX(id) FROM discovery_runs)
+ORDER BY p.category, p.name, s.name;
+```
+
+### Validators Used
+
+```sql
+SELECT validator_name, COUNT(*) as checks_run
+FROM validator_checks
+WHERE run_id = (SELECT MAX(id) FROM discovery_runs)
+GROUP BY validator_name
+ORDER BY checks_run DESC;
+```

package/skills/freshie-inventory/references/examples.md

@@ -0,0 +1,183 @@
+# Freshie Inventory Manager — Usage Examples
+
+Detailed input/output examples for each workflow.
+
+## Table of Contents
+
+- [Quick Status Check](#quick-status-check)
+- [Full Audit with Email Report](#full-audit-with-email-report)
+- [Ad-Hoc Query with Follow-Up](#ad-hoc-query-with-follow-up)
+- [Remediation Cycle](#remediation-cycle)
+- [Compare Discovery Runs](#compare-discovery-runs)
+- [Pack Coverage Analysis](#pack-coverage-analysis)
+
+## Quick Status Check
+
+```
+User: freshie status
+Assistant: [Skips menu — clear intent detected]
+           [Runs dashboard queries]
+
+FRESHIE INVENTORY DASHBOARD
+============================
+Last Scan:     Run #4 — 2026-03-23 (14 days ago)
+Plugins:       408
+Skills:        3123
+Packs:         63
+
+Grade Distribution:
+  A: 1180  B: 2074  C: 13  D: 9
+
+Staleness: CRITICAL (14 days)
+  Recommend running a new discovery scan.
+
+WORKFLOW COMPLETE — Would you like a PDF report emailed?
+  - Yes, email me
+  - No thanks
+
+User: no thanks
+```
+
+## Full Audit with Email Report
+
+```
+User: run a full ecosystem audit
+Assistant: [Shows menu — user selected "Full Audit"]
+           Starting full audit pipeline...
+
+           [Launches 3 parallel subagents:]
+           - discovery-scanner: Running rebuild-inventory.py...
+           - compliance-validator: Running enterprise validation...
+           - anomaly-detector: Checking data quality...
+
+           [All subagents complete]
+
+FRESHIE ECOSYSTEM REPORT — 2026-04-06
+================================================================
+Discovery: Run #5 (2026-04-06)
+  Plugins: 416 (+8) | Skills: 3200 (+77) | Packs: 63
+
+Compliance:
+  A: 1250 (39.1%) | B: 2050 (64.1%) | C: 10 (0.3%) | D: 5 (0.2%)
+  Average: 87/100
+
+Anomalies: 3 found
+  - 5 skills with word count < 50
+  - 2 plugins with no skills
+  - 1 pack below minimum viable
+
+WORKFLOW COMPLETE — Would you like a PDF report emailed?
+  - Yes, email me
+  - Yes, email someone
+  - Save PDF only
+  - No thanks
+
+User: yes email me
+Assistant: [Writes /tmp/freshie-report-2026-04-06.md]
+           [Converts to PDF via md-to-pdf.py]
+           [Invokes /email skill to send]
+           Sent "Freshie Ecosystem Report — 2026-04-06" to jeremy@intentsolutions.io
+           with freshie-report-2026-04-06.pdf attached.
+```
+
+## Ad-Hoc Query with Follow-Up
+
+```
+User: show me all D and F grade skills
+Assistant: [Routes to Workflow E: Query]
+           [Loads common-queries.md, runs Low-Grade Skills query]
+
+| skill_path | score | grade | errors | warnings |
+|------------|-------|-------|--------|----------|
+| plugins/database/data-validation-engine/... | 62 | D | 3 | 5 |
+| plugins/devops/ci-pipeline-builder/...      | 58 | F | 5 | 7 |
+| ...                                          |    |   |   |   |
+
+5 skills found with grade D or F.
+
+What next?
+  - Refine query
+  - Export to CSV
+  - Back to menu
+
+User: export to csv
+Assistant: [Writes freshie/exports/low-grade-skills.csv]
+           Exported 5 rows to freshie/exports/low-grade-skills.csv
+
+WORKFLOW COMPLETE — Would you like a PDF report emailed?
+  - Yes, email me
+  - No thanks
+```
+
+## Remediation Cycle
+
+```
+User: remediate skills
+Assistant: [Routes to Workflow D: Remediation]
+           Running dry-run first...
+
+           [Runs batch-remediate.py --dry-run]
+
+REMEDIATION PREVIEW
+================================================================
+  12 skills: Add missing 'compatible-with' field
+   8 skills: Fix tag formatting
+   3 agents: Add missing 'description' field
+  23 total changes
+
+Proceed?
+  - Execute
+  - Cancel
+
+User: Execute
+Assistant: [Runs batch-remediate.py --all --execute]
+           23 fixes applied.
+
+           Running compliance re-check...
+           [Launches compliance-validator subagent]
+
+           Grade improvements:
+             C -> B: 5 skills
+             D -> C: 2 skills
+           Average score: 87.3 -> 88.1 (+0.8)
+
+WORKFLOW COMPLETE — Would you like a PDF report emailed?
+```
+
+## Compare Discovery Runs
+
+```
+User: compare the last two runs
+Assistant: [Routes to Workflow F: Compare Runs]
+
+           Available runs:
+             Run #1 — 2026-03-21 | 349 plugins | 1426 skills
+             Run #2 — 2026-03-22 | 343 plugins | 1463 skills
+             Run #3 — 2026-03-22 | (incomplete)
+             Run #4 — 2026-03-23 | 408 plugins | 3123 skills
+
+           Comparing Run #2 -> Run #4:
+
+           Plugins: 343 -> 408 (+65)
+           Skills:  1463 -> 3123 (+1660)
+
+           Grade changes:
+             A: 520 -> 1180 (+660)
+             B: 930 -> 2074 (+1144)
+             Upgrades: 45 | Downgrades: 3
+```
+
+## Pack Coverage Analysis
+
+```
+User: which packs need more skills?
+Assistant: [Routes to Workflow I: Pack Coverage]
+
+           Packs below minimum viable (< 3 skills):
+           | Pack | Skills | Category |
+           |------|--------|----------|
+           | acme-pack | 1 | saas-packs |
+           | demo-pack | 2 | saas-packs |
+
+           2 packs need attention.
+```