# GravityClaw — Automated Asset Discovery & Upgrade Funnel

> **System**: GravityClaw
> **Parent**: SupraForge → AaaS (Agents as a Service)
> **Location**: `~/.gemini/gravityclaw/`
> **Purpose**: Fully automated pipeline that discovers, qualifies, upgrades, and publishes AI agent skills — running daily with zero human intervention.

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        GravityClaw Daily Pipeline                       │
│                                                                         │
│  07:00  ──►  07:15  ──►  07:30  ──►  09:00  ──►  11:00  ──►  11:30   │
│  SCOUT      INTAKE      FORGE       DIGEST      PUBLISHER    SYNC      │
│                                                                         │
│  Research → Activate → Score+Upgrade → Curate → Publish → Push to AaaS │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Pipeline Stages

### 1. Scout — `07:00 AM` Daily

**File**: `src/scout/index.ts`
**Schedule**: `src/scout/schedule.ts` — Cron: `0 7 * * *`
**Tools**: `src/tools/scout-tools.ts` — `scout_run`, `scout_status`, `scout_search`

**Purpose**: Automated research agent that scans configured sources (GitHub, npm, community feeds) for new AI skills, tools, techniques, and patterns.

**Process**:
1. Queries configured source feeds and registries
2. Filters for AI/agent-related assets (skills, MCP servers, prompt techniques)
3. Scores relevance and novelty against existing inventory
4. Stores qualified candidates in scout database (`scout.db`)
5. Produces candidate list for intake processing

**Output**: Scout database entries with metadata, URLs, descriptions, and relevance scores.

**Key Config**:
- Sources: GitHub trending, npm registry, awesome-lists, community feeds
- Minimum relevance threshold for intake pass-through
- Deduplication against existing vault inventory

---

### 2. Intake — Immediate (post-Scout)

**File**: `src/intake/activator.ts`
**Trigger**: Called by Scout or manually via agent tools

**Purpose**: Converts raw scout discoveries into structured SKILL.md files and activates them into the skill system.

**Process**:
1. Receives candidate from Scout
2. Classifies asset type: `package` | `technique` | `tool`
3. Generates structured SKILL.md with frontmatter metadata
4. Writes to `~/.agents/skills/shared/{category}/{name}/SKILL.md`
5. **Mirrors to Vault** → copies SKILL.md to `~/.gemini/aaas-vault/skills/{category}/{name}/`

**Bridge Function** (`mirrorToVault()`):
```typescript
// Bridges the directory gap between intake output and forge input
// Intake writes: ~/.agents/skills/shared/
// Forge reads:   ~/.gemini/aaas-vault/
function mirrorToVault(skillDir: string, skillName: string, category: string): void
```

**Output**: Structured SKILL.md files in both skill directory and vault directory.

---

### 3. Forge — `07:30 AM` Daily

**File**: `src/forge/index.ts`
**Schedule**: `src/forge/schedule.ts` — Cron: `30 7 * * *`
**Tools**: `src/tools/forge-tools.ts` — `forge_run`, `forge_status`, `forge_score`

**Purpose**: 7-stage quality pipeline that scores, enriches, upgrades, and exports skills to production tiers.

**Pipeline Stages**:

| # | Stage | File | Purpose |
|---|-------|------|---------|
| 1 | **SCAN** | `forge/scanner.ts` | Discovers SKILL.md files in the aaas-vault |
| 2 | **SCORE** | `forge/scorer.ts` | 6-dimension quality scoring (0-10 scale) |
| 3 | **NORMALIZE** | `forge/normalizer.ts` | Standardizes frontmatter and structure |
| 4 | **ENRICH** | `forge/enricher.ts` | LLM-powered content enhancement |
| 5 | **UPGRADE** | `forge/upgrader.ts` | Substantial content addition (4 new sections) |
| 6 | **CONVERT** | `forge/converter.ts` | Format conversion and optimization |
| 7 | **EXPORT** | `forge/exporter.ts` | Tier-based export to production directory |

**Scoring Dimensions** (scorer.ts):

| Dimension | Max Points | What It Measures |
|-----------|-----------|------------------|
| Frontmatter | 2 | Required fields present and valid |
| Naming | 2 | Follows naming conventions |
| Description | 1 | Clear, informative description |
| Body | 3 | Content depth and completeness |
| Structure | 2 | Proper markdown structure |
| Metadata | 2 | Tags, categories, versioning |
| Security | -10 | Penalty for security issues |

**Raw max**: 12, normalized to 0-10 scale.

**Tier Thresholds**:
- 🥇 **Gold** ≥ 8.0 — Production-ready, fully enriched
- 🥈 **Silver** ≥ 5.0 — Good quality, may need minor improvements
- 🥉 **Bronze** ≥ 3.0 — Functional but needs work
- ❌ **Rejected** < 3.0 — Does not meet minimum quality

**Upgrader Stage** (upgrader.ts) — The "Substantial Upgrade":

Targets Silver and Gold tier skills. Adds 4 context-ready sections:

1. **When to Use** — Decision framework with concrete scenarios
2. **Typical Workflow** — Step-by-step integration guide
3. **Practical Examples** — 2-3 real-world code/config examples
4. **Context Awareness** — How to adapt the skill to different project contexts

**Attribution Preservation** (enricher.ts):

The enricher preserves source attribution fields during frontmatter rebuild:
- `source_url` — Original discovery URL
- `author` — Original author/creator
- `license` — Original license type
- `discovered_by` — "GravityClaw Scout"
- `upgraded_by` — "GravityClaw Forge"

**Output**:
- Tiered skills exported to `~/antigravity-skills/skills/{category}/{id}/`
- Forge manifest at `~/antigravity-skills/.forge-run.json`

---

### 4. Digest — `09:00 AM` Daily

**File**: `src/digest/curator.ts`
**Schedule**: `src/digest/schedule.ts` — Cron: `0 9 * * *`

**Purpose**: Curates daily summary of all pipeline activity — both scout discoveries and forge processing results.

**Process**:
1. Collects scout candidates from last 24 hours
2. Collects forge results from `~/antigravity-skills/.forge-run.json` (last 24h)
3. Merges and deduplicates items
4. Generates curated digest with categories and highlights
5. Produces formatted report for publisher

**Data Sources**:
- Scout database (new discoveries)
- Forge manifest (processing results, tier distribution)

**Output**: Curated `DigestItem[]` array with title, source, category, summary, and URLs.

---

### 5. Publisher — `11:00 AM` Daily

**File**: `src/publisher/collector.ts`
**Schedule**: `src/publisher/schedule.ts` — Cron: `0 11 * * *`

**Purpose**: Publishes daily pipeline results as formatted content, including forge statistics.

**Process**:
1. Collects digest items
2. Collects forge statistics (tier distribution, LLM enrichment count, export count)
3. Generates publication-ready content (markdown, audio scripts)
4. Drops to publication directory

**Stats Collected**:
```typescript
interface ForgeStats {
  exported: number;
  llmEnriched: number;
  tierDistribution: Record<string, number>; // { gold: N, silver: N, bronze: N }
  completedAt: string;
}
```

**Output**: Publication-ready content with full pipeline statistics.

---

### 6. AaaS Sync — `11:30 AM` Daily (Post-Publisher)

**File**: `src/aaas-sync/index.ts`
**Purpose**: Bridge between GravityClaw local pipeline and AaaS cloud platform.

**Process**:
1. Reads exported Gold/Silver skills from `~/antigravity-skills/`
2. Transforms to AaaS entity format
3. Pushes to Firestore `audio_episodes` collection
4. Triggers podcast feed update at `aaas.blog/api/podcast/feed`

**Firestore Document Schema**:
```typescript
{
  type: string;           // "entity" | "channel_digest"
  slug: string;           // Skill identifier
  entityName: string;     // Human-readable name
  duration: number;       // Audio duration (seconds)
  audioUrl: string;       // TTS audio file URL
  generatedAt: string;    // ISO timestamp
  script: string;         // Generated narration
  provider: string;       // TTS provider
  generatedBy: string;    // "gravityclaw-sync"
}
```

---

## Voice & Podcast System

**File**: `src/voice/synthesize.ts` — Google Cloud TTS → OGG Opus
**File**: `src/voice/podcast.ts` — 3 podcast concept generators
**File**: `src/voice/schedule.ts` — Podcast scheduling
**Tools**: `src/tools/voice-tools.ts` — `podcast_generate`, `podcast_list`, `podcast_status`

### Podcast Concepts

| Concept | ID | Format | Duration |
|---------|-----|--------|----------|
| **Field Report** | `field-report` | Narrated scout discovery story | 2-3 min |
| **Discovery Digest** | `discovery-digest` | Daily summary of all pipeline output | 5-7 min |
| **Deep Dive** | `deep-dive` | Technical analysis of a single Gold skill | 8-12 min |

---

## Health & Monitoring

**File**: `src/tools/health-tools.ts` — `health_check`, `health_timeline`, `health_repair`

**Monitors**:
- Schedule registration (all 5 cron jobs active)
- Database connectivity (scout.db, forge manifest)
- Directory accessibility (vault, export, skills)
- Pipeline recency (last run timestamps within 24h)
- Tier distribution trends

---

## Directory Map

```
~/.gemini/gravityclaw/
├── src/
│   ├── index.ts                 # Main entry — registers all schedules
│   ├── scout/
│   │   ├── index.ts             # Scout orchestrator
│   │   └── schedule.ts          # 07:00 cron
│   ├── intake/
│   │   └── activator.ts         # Asset activation + vault mirror
│   ├── forge/
│   │   ├── index.ts             # 7-stage pipeline orchestrator
│   │   ├── scanner.ts           # Stage 1: SCAN
│   │   ├── scorer.ts            # Stage 2: SCORE (6 dimensions)
│   │   ├── normalizer.ts        # Stage 3: NORMALIZE
│   │   ├── enricher.ts          # Stage 4: ENRICH (LLM + attribution)
│   │   ├── upgrader.ts          # Stage 5: UPGRADE (4 context sections)
│   │   ├── converter.ts         # Stage 6: CONVERT
│   │   ├── exporter.ts          # Stage 7: EXPORT (tier-based)
│   │   ├── types.ts             # ForgeRunResult, ForgeConfig, tiers
│   │   └── schedule.ts          # 07:30 cron
│   ├── digest/
│   │   ├── curator.ts           # Daily digest curation
│   │   └── schedule.ts          # 09:00 cron
│   ├── publisher/
│   │   ├── collector.ts         # Publication assembly + forge stats
│   │   └── schedule.ts          # 11:00 cron
│   ├── voice/
│   │   ├── synthesize.ts        # Google Cloud TTS engine
│   │   ├── podcast.ts           # 3 concept generators
│   │   └── schedule.ts          # Podcast scheduling
│   ├── aaas-sync/
│   │   └── index.ts             # Firestore bridge to AaaS
│   ├── tools/
│   │   ├── index.ts             # Barrel file (self-registering imports)
│   │   ├── scout-tools.ts       # scout_run, scout_status, scout_search
│   │   ├── forge-tools.ts       # forge_run, forge_status, forge_score
│   │   ├── voice-tools.ts       # podcast_generate, podcast_list, podcast_status
│   │   └── health-tools.ts      # health_check, health_timeline, health_repair
│   └── db/
│       └── schema.ts            # Database schema (scout + forge tables)
│
├── data/
│   └── scout.db                 # SQLite scout database
│
└── package.json

~/.gemini/aaas-vault/     # Forge input (mirrored from intake)
│   └── skills/{category}/{name}/SKILL.md

~/antigravity-skills/            # Forge output (exported production skills)
│   ├── skills/{category}/{id}/SKILL.md
│   └── .forge-run.json          # Latest forge run manifest
```

---

## Schedule Summary

| Time | Stage | Cron | Task Name |
|------|-------|------|-----------|
| 07:00 | Scout | `0 7 * * *` | `daily-scout` |
| 07:15 | Intake | — | Triggered by Scout |
| 07:30 | Forge | `30 7 * * *` | `daily-vault-forge` |
| 09:00 | Digest | `0 9 * * *` | `daily-digest` |
| 11:00 | Publisher | `0 11 * * *` | `daily-publisher` |
| 11:30 | AaaS Sync | — | Triggered by Publisher |

---

## Source Attribution Model

**Philosophy**: "Honor the origin, but make each asset substantially our own."

Every skill processed through GravityClaw carries:

1. **Origin fields preserved**: `source_url`, `author`, `license` — never stripped
2. **Transformation fields added**: `discovered_by: "GravityClaw Scout"`, `upgraded_by: "GravityClaw Forge"`
3. **Substantial value-add**: The Upgrader stage adds 4 original sections (When to Use, Workflow, Examples, Context Awareness) that constitute a meaningful transformation beyond the original asset
4. **Quality certification**: Tier badge (Gold/Silver/Bronze) indicates our quality assessment

This model respects open-source licensing while creating genuinely differentiated, context-engineered assets.

---

## Transfer Guide

To replicate this system on another machine:

1. **Clone GravityClaw**: `~/.gemini/gravityclaw/` — the full pipeline codebase
2. **Create directories**:
   - `~/.gemini/aaas-vault/skills/` — forge input staging
   - `~/antigravity-skills/skills/` — forge output / production skills
3. **Install dependencies**: `cd ~/.gemini/gravityclaw && npm install`
4. **Build**: `npm run build`
5. **Configure**: Set Google Cloud TTS credentials for voice features
6. **Set up Firebase**: Place service account key for AaaS sync
7. **Start**: The entry point (`src/index.ts`) auto-registers all schedules on boot

**Environment Variables**:
- `GOOGLE_APPLICATION_CREDENTIALS` — GCP service account for TTS
- `AAAS_FIREBASE_SA_PATH` — Firebase service account for Firestore sync
- `GRAVITYCLAW_VAULT_PATH` — Override default vault path (optional)
- `GRAVITYCLAW_EXPORT_PATH` — Override default export path (optional)