# scribase insights

Analyzes a live environment or an offline schema snapshot for improvements. It
reports findings across three dimensions: missing RLS policies, suboptimal
indexes, and slow query patterns.

## Usage

### Analyze a live environment

```sh
scribase insights <org> <project> <env>
```

Connects to the live environment via the management API and analyzes its current
state. Requires `SCRIBASE_API_URL` and `SCRIBASE_ACCESS_TOKEN`.

### Analyze offline (no server)

```sh
scribase insights \
  --policies schema.scribase \
  --tables schema.scribase \
  [--statements queries.sql] \
  [--foreign-keys schema.scribase] \
  [--json]
```

All inputs are read locally — no API call is made. Useful for CI policy audits.

## Options (offline mode)

| Flag | Description |
|---|---|
| `--policies <file>` | Schema file to analyze for policy coverage (`F` = skip) |
| `--tables <file>` | Schema file to analyze for missing indexes |
| `--statements <file>` | SQL file of representative queries for index advice |
| `--foreign-keys <file>` | Schema file to check for unindexed foreign keys |
| `--json` | Output findings as JSON |

## Output

Each finding has:

- **severity** — `critical`, `high`, `medium`, `info`
- **confidence** — `certain`, `likely`, `possible`
- **message** — description of the finding
- **remediation** — suggested fix (SQL or policy syntax)

Example:

```json
{
  "findings": [
    {
      "severity": "critical",
      "confidence": "certain",
      "message": "Table 'orders' has no RLS policies and RLS is not enabled.",
      "remediation": "ALTER TABLE orders ENABLE ROW LEVEL SECURITY;"
    },
    {
      "severity": "high",
      "confidence": "likely",
      "message": "Foreign key orders.user_id is not indexed.",
      "remediation": "CREATE INDEX ON orders (user_id);"
    }
  ]
}
```

## Notes

- `scribase insights` is read-only. It does not modify the database.
- In live mode the API fetches real query statistics from `pg_stat_statements`.
- In offline mode only structural analysis is possible (no query statistics).
- Run in CI with `--json` to fail the build on critical findings.