javi-forge 0.1.0

package/ai-config/skills/database/timescaledb/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: timescaledb
+description: >
+  TimescaleDB time-series database patterns with hypertables, continuous aggregates, and compression.
+  Trigger: TimescaleDB, time-series, hypertable, continuous aggregate, time bucket, PostgreSQL time-series
+tools:
+  - Read
+  - Write
+  - Bash
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [timescaledb, postgresql, time-series, database, iot]
+  updated: "2026-02"
+---
+
+# TimescaleDB Time-Series Database
+
+Patterns for time-series data with TimescaleDB.
+
+## Stack
+
+```yaml
+TimescaleDB: 2.14+
+PostgreSQL: 16+
+```
+
+## Docker Setup
+
+```yaml
+services:
+  timescaledb:
+    image: timescale/timescaledb:latest-pg16
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app
+    ports:
+      - "5432:5432"
+    volumes:
+      - timescale_data:/var/lib/postgresql/data
+    command: >
+      postgres
+      -c shared_preload_libraries=timescaledb
+      -c timescaledb.max_background_workers=8
+```
+
+## Hypertable Creation
+
+```sql
+-- Enable extension
+CREATE EXTENSION IF NOT EXISTS timescaledb;
+
+-- Create table
+CREATE TABLE readings (
+    time        TIMESTAMPTZ NOT NULL,
+    sensor_id   UUID NOT NULL,
+    tenant_id   UUID NOT NULL,
+    value       DOUBLE PRECISION NOT NULL,
+    quality     SMALLINT DEFAULT 192
+);
+
+-- Convert to hypertable
+SELECT create_hypertable(
+    'readings',
+    'time',
+    chunk_time_interval => INTERVAL '1 day',
+    if_not_exists => TRUE
+);
+
+-- Add space partitioning for multi-tenant
+SELECT add_dimension('readings', 'tenant_id', number_partitions => 4);
+
+-- Create indexes
+CREATE INDEX idx_readings_sensor_time ON readings (sensor_id, time DESC);
+CREATE INDEX idx_readings_tenant_time ON readings (tenant_id, time DESC);
+
+-- Enable compression
+ALTER TABLE readings SET (
+    timescaledb.compress,
+    timescaledb.compress_segmentby = 'sensor_id, tenant_id',
+    timescaledb.compress_orderby = 'time DESC'
+);
+
+-- Add compression policy
+SELECT add_compression_policy('readings', INTERVAL '7 days');
+```
+
+## Continuous Aggregates
+
+### Hourly Aggregates
+
+```sql
+CREATE MATERIALIZED VIEW readings_hourly
+WITH (timescaledb.continuous) AS
+SELECT
+    time_bucket('1 hour', time) AS bucket,
+    sensor_id,
+    tenant_id,
+    AVG(value) AS avg_value,
+    MIN(value) AS min_value,
+    MAX(value) AS max_value,
+    COUNT(*) AS count,
+    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY value) AS median
+FROM readings
+GROUP BY bucket, sensor_id, tenant_id
+WITH NO DATA;
+
+-- Refresh policy
+SELECT add_continuous_aggregate_policy('readings_hourly',
+    start_offset => INTERVAL '2 hours',
+    end_offset => INTERVAL '1 hour',
+    schedule_interval => INTERVAL '1 hour'
+);
+
+-- Enable real-time aggregation
+ALTER MATERIALIZED VIEW readings_hourly SET (
+    timescaledb.materialized_only = false
+);
+```
+
+### Daily Aggregates
+
+```sql
+CREATE MATERIALIZED VIEW readings_daily
+WITH (timescaledb.continuous) AS
+SELECT
+    time_bucket('1 day', time) AS bucket,
+    sensor_id,
+    tenant_id,
+    AVG(value) AS avg_value,
+    MIN(value) AS min_value,
+    MAX(value) AS max_value,
+    COUNT(*) AS count
+FROM readings
+GROUP BY bucket, sensor_id, tenant_id
+WITH NO DATA;
+
+SELECT add_continuous_aggregate_policy('readings_daily',
+    start_offset => INTERVAL '3 days',
+    end_offset => INTERVAL '1 day',
+    schedule_interval => INTERVAL '1 day'
+);
+```
+
+## Time-Series Queries
+
+### Time Bucket
+
+```sql
+SELECT
+    time_bucket('15 minutes', time) AS period,
+    sensor_id,
+    AVG(value) AS avg_value,
+    COUNT(*) AS readings
+FROM readings
+WHERE sensor_id = $1 AND time > NOW() - INTERVAL '24 hours'
+GROUP BY period, sensor_id
+ORDER BY period DESC;
+```
+
+### Gap Filling
+
+```sql
+SELECT
+    time_bucket_gapfill('1 hour', time) AS period,
+    sensor_id,
+    COALESCE(AVG(value), interpolate(AVG(value))) AS value,
+    locf(AVG(value)) AS last_known
+FROM readings
+WHERE sensor_id = $1 AND time BETWEEN '2024-01-01' AND '2024-01-02'
+GROUP BY period, sensor_id
+ORDER BY period;
+```
+
+### Latest Per Sensor
+
+```sql
+SELECT DISTINCT ON (sensor_id)
+    sensor_id,
+    time AS last_time,
+    value AS last_value
+FROM readings
+WHERE tenant_id = $1
+ORDER BY sensor_id, time DESC;
+
+-- Or using first/last
+SELECT
+    sensor_id,
+    last(value, time) AS last_value,
+    last(time, time) AS last_time
+FROM readings
+WHERE tenant_id = $1 AND time > NOW() - INTERVAL '1 hour'
+GROUP BY sensor_id;
+```
+
+### Change Detection
+
+```sql
+WITH delta AS (
+    SELECT
+        time,
+        sensor_id,
+        value,
+        value - LAG(value) OVER (PARTITION BY sensor_id ORDER BY time) AS change,
+        ABS(value - LAG(value) OVER (PARTITION BY sensor_id ORDER BY time))
+            / NULLIF(LAG(value) OVER (PARTITION BY sensor_id ORDER BY time), 0) * 100 AS pct_change
+    FROM readings
+    WHERE sensor_id = $1
+)
+SELECT * FROM delta WHERE ABS(pct_change) > 10
+ORDER BY time DESC;
+```
+
+## Retention Policies
+
+```sql
+-- Raw data: 90 days
+SELECT add_retention_policy('readings', INTERVAL '90 days');
+
+-- Aggregates: longer
+SELECT add_retention_policy('readings_hourly', INTERVAL '2 years');
+SELECT add_retention_policy('readings_daily', INTERVAL '5 years');
+
+-- View policies
+SELECT * FROM timescaledb_information.jobs WHERE proc_name = 'policy_retention';
+
+-- Manual drop
+SELECT drop_chunks('readings', older_than => INTERVAL '90 days');
+```
+
+## Go Integration
+
+```go
+type Reading struct {
+    Time     time.Time `db:"time"`
+    SensorID string    `db:"sensor_id"`
+    TenantID string    `db:"tenant_id"`
+    Value    float64   `db:"value"`
+    Quality  int16     `db:"quality"`
+}
+
+// Batch insert with COPY
+func (r *Repository) InsertBatch(ctx context.Context, readings []Reading) error {
+    _, err := r.pool.CopyFrom(
+        ctx,
+        pgx.Identifier{"readings"},
+        []string{"time", "sensor_id", "tenant_id", "value", "quality"},
+        pgx.CopyFromSlice(len(readings), func(i int) ([]any, error) {
+            return []any{
+                readings[i].Time,
+                readings[i].SensorID,
+                readings[i].TenantID,
+                readings[i].Value,
+                readings[i].Quality,
+            }, nil
+        }),
+    )
+    return err
+}
+
+// Aggregated query
+func (r *Repository) GetAggregated(ctx context.Context, sensorID string, start, end time.Time, bucket string) ([]Aggregate, error) {
+    query := `
+        SELECT time_bucket($1, time) AS bucket, AVG(value), MIN(value), MAX(value), COUNT(*)
+        FROM readings
+        WHERE sensor_id = $2 AND time BETWEEN $3 AND $4
+        GROUP BY bucket ORDER BY bucket DESC
+    `
+    rows, err := r.pool.Query(ctx, query, bucket, sensorID, start, end)
+    // ...
+}
+```
+
+## Python Integration
+
+```python
+async def insert_readings(pool, readings: list[Reading]) -> None:
+    async with pool.acquire() as conn:
+        await conn.copy_records_to_table(
+            'readings',
+            records=[(r.time, r.sensor_id, r.tenant_id, r.value, r.quality) for r in readings],
+            columns=['time', 'sensor_id', 'tenant_id', 'value', 'quality']
+        )
+
+async def get_aggregated(pool, sensor_id: str, start: datetime, end: datetime, bucket: str = '1 hour'):
+    query = """
+        SELECT time_bucket($1::interval, time) AS bucket, AVG(value), MIN(value), MAX(value), COUNT(*)
+        FROM readings WHERE sensor_id = $2 AND time BETWEEN $3 AND $4
+        GROUP BY bucket ORDER BY bucket DESC
+    """
+    async with pool.acquire() as conn:
+        return await conn.fetch(query, bucket, sensor_id, start, end)
+```
+
+## Performance Tips
+
+1. **Use COPY for bulk inserts** - Much faster than INSERT
+2. **Tune chunk size** - Based on data volume
+3. **Use continuous aggregates** - For dashboards
+4. **Compression** - Enable after data stabilizes
+5. **Partial indexes** - For recent data queries
+
+```sql
+-- Partial index for recent data
+CREATE INDEX idx_recent ON readings (sensor_id, time DESC)
+WHERE time > NOW() - INTERVAL '7 days';
+
+-- Check compression stats
+SELECT hypertable_name, before_compression_total_bytes, after_compression_total_bytes,
+    (1 - after_compression_total_bytes::float / before_compression_total_bytes) * 100 AS ratio
+FROM chunk_compression_stats('readings');
+```
+
+## Related Skills
+
+- `pgx-postgres`: PostgreSQL driver patterns
+- `redis-cache`: Hot data caching
+- `duckdb-analytics`: Analytics queries
+- `opentelemetry`: Metrics storage

package/ai-config/skills/docs/api-documentation/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: api-documentation
+description: >
+  API documentation concepts. OpenAPI/Swagger, interactive docs, versioning, examples.
+  Trigger: API docs, OpenAPI, Swagger, Redoc, documentation, API reference
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+metadata:
+  author: apigen-team
+  version: "1.0"
+  tags: [documentation, openapi, swagger, api]
+  scope: ["**/docs/**"]
+---
+
+# API Documentation Concepts
+
+## OpenAPI Specification (OAS)
+
+### Structure
+```yaml
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+  description: API description with **markdown** support
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://staging-api.example.com/v1
+    description: Staging
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email]
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+```
+
+### Key Elements
+```
+Info: API metadata, contact, license
+Servers: Base URLs for environments
+Paths: Endpoints and operations
+Components: Reusable schemas, parameters, responses
+Tags: Logical grouping of operations
+Security: Authentication schemes
+```
+
+## Documentation Tools
+
+### Swagger UI
+```
+Features:
+- Interactive API explorer
+- Try it out functionality
+- Authorization support
+- Request/response examples
+
+Best for:
+- Developer testing
+- Internal documentation
+- Quick prototyping
+```
+
+### Redoc
+```
+Features:
+- Clean, professional look
+- Three-panel layout
+- Search functionality
+- No interactivity (reference only)
+
+Best for:
+- Public API documentation
+- Customer-facing docs
+- Embedded in websites
+```
+
+### Stoplight
+```
+Features:
+- Design-first approach
+- Mock servers
+- Style guides
+- Git integration
+
+Best for:
+- API design
+- Enterprise documentation
+- Team collaboration
+```
+
+## Documentation Best Practices
+
+### Descriptions
+```yaml
+# Good: Explains purpose and context
+description: |
+  Retrieves a paginated list of users in the organization.
+  Results are sorted by creation date, newest first.
+
+  **Note:** Requires `users:read` permission.
+
+# Bad: States the obvious
+description: Gets users
+```
+
+### Examples
+```yaml
+# Provide realistic examples
+schema:
+  type: object
+  properties:
+    email:
+      type: string
+      format: email
+      example: john.doe@example.com
+    createdAt:
+      type: string
+      format: date-time
+      example: "2024-01-15T10:30:00Z"
+
+# Multiple examples for different scenarios
+examples:
+  admin:
+    summary: Admin user
+    value:
+      id: "123"
+      email: "admin@example.com"
+      role: "admin"
+  regular:
+    summary: Regular user
+    value:
+      id: "456"
+      email: "user@example.com"
+      role: "user"
+```
+
+### Error Responses
+```yaml
+responses:
+  '400':
+    description: Validation error
+    content:
+      application/problem+json:
+        schema:
+          $ref: '#/components/schemas/ProblemDetail'
+        examples:
+          invalidEmail:
+            summary: Invalid email format
+            value:
+              type: "https://api.example.com/errors/validation"
+              title: "Validation Error"
+              status: 400
+              detail: "Invalid email format"
+              errors:
+                - field: "email"
+                  message: "Must be a valid email address"
+```
+
+## API Versioning Documentation
+
+### URL Versioning
+```yaml
+servers:
+  - url: https://api.example.com/v1
+  - url: https://api.example.com/v2
+
+paths:
+  /v1/users:
+    deprecated: true
+    x-deprecation-date: 2024-06-01
+```
+
+### Header Versioning
+```yaml
+parameters:
+  - name: API-Version
+    in: header
+    required: false
+    schema:
+      type: string
+      default: "2024-01-01"
+      enum:
+        - "2024-01-01"
+        - "2023-06-01"
+```
+
+## Authentication Documentation
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        JWT token obtained from `/auth/login`.
+        Token expires after 1 hour.
+
+    apiKey:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: |
+        API key for server-to-server communication.
+        Contact support to obtain a key.
+
+    oauth2:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.example.com/authorize
+          tokenUrl: https://auth.example.com/token
+          scopes:
+            users:read: Read user information
+            users:write: Create and update users
+```
+
+## Changelog & Migration
+
+```markdown
+## API Changelog
+
+### v2.0.0 (2024-01-15)
+#### Breaking Changes
+- `GET /users` now returns paginated response
+- `email` field renamed to `emailAddress`
+
+#### New Features
+- Added `GET /users/{id}/preferences`
+- Added filtering by `status` parameter
+
+### v1.5.0 (2023-12-01)
+#### Deprecations
+- `GET /users/all` deprecated, use `GET /users` with pagination
+```
+
+## Documentation-as-Code
+
+```
+Benefits:
+- Version controlled
+- Review process
+- CI/CD integration
+- Single source of truth
+
+Workflow:
+1. Write OpenAPI spec (YAML/JSON)
+2. Review changes via PR
+3. Generate docs on merge
+4. Deploy to documentation site
+5. Generate SDKs from spec
+```
+
+## Related Skills
+
+- `docs-spring`: Spring Boot API documentation
+- `apigen-architecture`: Overall system architecture
+
+