loki-mode 9.8.0 → 9.12.0

package/docs/alternative-installations.md

@@ -14,7 +14,6 @@ git clone https://github.com/asklokesh/loki-mode.git ~/.claude/skills/loki-mode
 
 # Optionally symlink for other providers:
 ln -sf ~/.claude/skills/loki-mode ~/.codex/skills/loki-mode
-ln -sf ~/.claude/skills/loki-mode ~/.gemini/skills/loki-mode
 
 # Optionally add CLI to PATH:
 ln -sf ~/.claude/skills/loki-mode/autonomy/loki /usr/local/bin/loki
@@ -28,7 +27,7 @@ ln -sf ~/.claude/skills/loki-mode/autonomy/loki /usr/local/bin/loki
 
 ## Docker
 
-**Status:** Image exists on Docker Hub. Tags: `latest`, version-specific (e.g., `8.0.0`).
+**Status:** Image exists on Docker Hub. Tags: `latest`, version-specific (e.g., `9.8.0`).
 
 ```bash
 docker pull asklokesh/loki-mode:latest
@@ -84,7 +83,7 @@ jobs:
 | Input | Default | Description |
 |-------|---------|-------------|
 | `mode` | `review` | `review`, `fix`, or `test` |
-| `provider` | `claude` | `claude` (recommended), `codex`, `cline`, or `aider`. `gemini` is DEPRECATED (v7.5.18). |
+| `provider` | `claude` | `claude` (recommended), `cline`, `codex`, `aider`, or `opencode`. `gemini` was REMOVED in v7.5.18. |
 | `budget_limit` | `5.00` | Max cost in USD |
 | `max_iterations` | `3` | Max RARV cycles |
 | `github_token` | (required) | GitHub token for PR comments |

package/docs/audit-logging.md

@@ -44,8 +44,8 @@ enterprise:
 |----------|---------|-------------|
 | `LOKI_AUDIT_DISABLED` | `false` | Set to `true` to disable audit logging |
 | `LOKI_ENTERPRISE_AUDIT` | `false` | Force audit on (legacy, audit is now on by default) |
-| `LOKI_AUDIT_LEVEL` | `info` | Minimum log level: debug, info, warning, error |
-| `LOKI_AUDIT_RETENTION` | `90` | Retention period in days |
+| `LOKI_AUDIT_MAX_SIZE_MB` | `10` | Rotate the log once it exceeds this size |
+| `LOKI_AUDIT_MAX_FILES` | `10` | Number of rotated log files to keep |
 | `LOKI_AUDIT_SYSLOG_HOST` | - | Syslog server hostname for forwarding |
 | `LOKI_AUDIT_SYSLOG_PORT` | `514` | Syslog server port |
 | `LOKI_AUDIT_SYSLOG_PROTO` | `udp` | Syslog protocol: `udp` or `tcp` |
@@ -202,33 +202,34 @@ loki enterprise audit tail --event session.start
 loki enterprise audit tail --level error
 ```
 
-### Search Logs
+### Search and export logs
+
+`loki enterprise audit` has exactly two subcommands: `summary` and `tail`.
+There is no `search` and no `export` (an earlier version of this page
+documented both, with filter flags that do not exist). The log is newline
+-delimited JSON on disk, so query and export it with ordinary tools:
 
 ```bash
-# Search by event
-loki enterprise audit search --event auth.fail
+AUDIT=~/.loki/dashboard/audit/audit.jsonl
+
+# Search by event type
+jq -c 'select(.event == "auth.fail")' "$AUDIT"
 
 # Search by date range
-loki enterprise audit search --from 2026-02-01 --to 2026-02-15
+jq -c 'select(.timestamp >= "2026-02-01" and .timestamp <= "2026-02-15")' "$AUDIT"
 
 # Search by actor
-loki enterprise audit search --actor ci-bot
+jq -c 'select(.actor == "ci-bot")' "$AUDIT"
 
-# Combined filters
-loki enterprise audit search --event task.fail --from 2026-02-15 --level error
+# Export a filtered slice
+jq -s 'map(select(.event == "task.fail"))' "$AUDIT" > errors.json
 ```
 
-### Export Logs
+The built-in views:
 
 ```bash
-# Export to file
-loki enterprise audit export --output audit-export.json
-
-# Export with filters
-loki enterprise audit export --from 2026-01-01 --level error --output errors.json
-
-# Export as CSV
-loki enterprise audit export --format csv --output audit.csv
+loki enterprise audit summary   # aggregate counts
+loki enterprise audit tail      # most recent entries
 ```
 
 ## API Endpoints
@@ -297,10 +298,10 @@ Each audit entry includes a `chain_hash` field:
 
 ### Verification
 
-```bash
-# Verify integrity via CLI
-loki audit verify
+There is no `loki audit verify` subcommand (`loki audit` has `log`, `count`,
+and `scan`). Verify the chain through the Python API:
 
+```bash
 # Python verification
 from dashboard.audit import verify_log_integrity
 
@@ -422,20 +423,25 @@ In addition to dashboard audit logs, agent actions are tracked separately.
 
 ### CLI Commands
 
+Note that `loki audit` reads the agent-action audit trail, which is a separate
+store from the enterprise audit log covered above.
+
 ```bash
-# View recent agent actions
+# View recent agent actions (optional positional line count, default 50)
 loki audit log
+loki audit log 200
 
 # Count total agent actions
 loki audit count
 
-# Filter by action type
-loki audit log --action git_commit
-
-# Show help
-loki audit help
+# Run a quality scan
+loki audit scan --preset default
 ```
 
+`loki audit log` takes a line count, not filter flags; an earlier version of
+this page showed `--action git_commit`, which is not implemented. Filter with
+`grep` or `jq` over `.loki/audit.jsonl` instead.
+
 ## Compliance
 
 ### SOC2
@@ -521,16 +527,18 @@ echo '{"test": "entry"}' >> ~/.loki/dashboard/audit/test.jsonl
 ### Missing Events
 
 ```bash
-# Check minimum level configuration
+# Check audit status and recent events
 loki enterprise audit summary
 
-# Lower level to capture more events
-export LOKI_AUDIT_LEVEL=debug
-
-# Check exclude_events in config
-cat .loki/config.yaml | grep -A 5 exclude_events
+# Confirm audit is not disabled (it is ON by default)
+echo "${LOKI_AUDIT_DISABLED:-unset}"
 ```
 
+There is no minimum-severity filter and no per-event exclude list. Audit
+logging is all-or-nothing: on by default, off with `LOKI_AUDIT_DISABLED=true`.
+`LOKI_AUDIT_LEVEL` and `LOKI_AUDIT_EXCLUDE_EVENTS` appeared in an earlier
+version of this page and were never implemented.
+
 ### Disk Space Issues
 
 ```bash
@@ -543,8 +551,9 @@ find ~/.loki/dashboard/audit/ -type f -size +100M
 # Manually clean old logs
 find ~/.loki/dashboard/audit/ -name "*.jsonl" -mtime +30 -delete
 
-# Enable compression
-export LOKI_AUDIT_COMPRESS=true
+# Bound disk use via rotation (there is no built-in compression option)
+export LOKI_AUDIT_MAX_SIZE_MB=5
+export LOKI_AUDIT_MAX_FILES=4
 ```
 
 ### Syslog Not Forwarding

package/docs/authentication.md

@@ -154,7 +154,18 @@ export LOKI_OIDC_CLIENT_ID=your-client-id
 | `LOKI_OIDC_ISSUER` | - | OIDC issuer URL (required) |
 | `LOKI_OIDC_CLIENT_ID` | - | OIDC client/application ID (required) |
 | `LOKI_OIDC_AUDIENCE` | *(client_id)* | Expected JWT audience claim |
-| `LOKI_OIDC_SCOPES` | `openid,email,profile` | OIDC scopes to request |
+| `LOKI_OIDC_ROLES_CLAIM` | - | Claim to read roles from; supports a dotted path |
+| `LOKI_OIDC_DEFAULT_ROLE` | `viewer` | Role applied when no recognized role claim is present |
+| `LOKI_OIDC_SKIP_SIGNATURE_VERIFY` | `false` | Allow the claims-only path without PyJWT. **Insecure**; see the warning below. |
+
+Scopes are requested by your identity provider configuration, not by Loki:
+there is no `LOKI_OIDC_SCOPES` variable (an earlier version of this page listed
+one). All of the above are read in `dashboard/auth.py`.
+
+**Install PyJWT and cryptography for any production deployment.** Without them
+JWT signatures are not cryptographically verified, and the claims-only path is
+refused unless you explicitly set `LOKI_OIDC_SKIP_SIGNATURE_VERIFY=true`.
+Running with signature verification off provides no authentication security.
 
 ### OIDC Flow
 
@@ -256,7 +267,7 @@ GET /auth/logout
 ### General
 
 1. Enable `LOKI_ENTERPRISE_AUTH` in production
-2. Enable `LOKI_TLS_ENABLED` for encrypted connections
+2. Set both `LOKI_TLS_CERT` and `LOKI_TLS_KEY` for encrypted connections (HTTPS turns on when both are present; there is no `LOKI_TLS_ENABLED` switch)
 3. Use audit logging to track authentication events
 4. Monitor failed authentication attempts
 5. Implement rate limiting on auth endpoints

package/docs/authorization.md

@@ -100,19 +100,27 @@ Security and compliance monitoring.
 
 ## Configuration
 
-### Enable RBAC
+### Enable enterprise auth
+
+There is no separate `LOKI_RBAC_ENABLED` switch. Role mapping is part of the
+enterprise auth path, enabled by `LOKI_ENTERPRISE_AUTH` for token auth and by
+`LOKI_OIDC_ISSUER` + `LOKI_OIDC_CLIENT_ID` for OIDC/SSO (`dashboard/auth.py`).
 
 ```bash
-export LOKI_RBAC_ENABLED=true
+export LOKI_ENTERPRISE_AUTH=true
 loki start ./prd.md
 ```
 
-### Assign Roles via Tokens
+### Assign scopes via tokens
+
+`loki enterprise token generate` takes `--scopes` (a comma-separated scope
+list), not a `--role` flag. Roles as such are resolved from OIDC claims; tokens
+carry scopes directly.
 
 ```bash
-# Generate token with role
-loki enterprise token generate dev-1 --role operator --expires 30
-loki enterprise token generate viewer-1 --role viewer --expires 90
+# Generate token with scopes
+loki enterprise token generate dev-1 --scopes control,read,write --expires 30
+loki enterprise token generate viewer-1 --scopes read --expires 90
 loki enterprise token generate auditor-1 --role auditor --expires 180
 loki enterprise token generate admin-1 --role admin --expires 365
 ```
@@ -228,81 +236,75 @@ loki enterprise token generate metrics-bot --role metrics_viewer
 
 ### CLI
 
-```bash
-# Check current permissions
-loki enterprise rbac check
-
-# Check specific permission
-loki enterprise rbac check --scope control
+There is no `loki enterprise rbac` subcommand. `loki enterprise` has exactly
+`status`, `token`, and `audit`. To see what a token can do, list the tokens and
+read their scopes:
 
-# List permissions for role
-loki enterprise rbac permissions --role operator
+```bash
+loki enterprise token list
+loki enterprise status
 ```
 
 ### API
 
+There is no `/api/enterprise/rbac/check` endpoint; an earlier version of this
+page documented one along with a `permissions` response object, and neither
+exists. Scopes are enforced per-route: each `/api/*` route declares the scope it
+requires via `Depends(auth.require_scope(...))` in `dashboard/server.py`. A
+request either succeeds or is rejected, so exercise the route you care about:
+
 ```bash
-# Check token permissions
-curl -H "Authorization: Bearer $LOKI_TOKEN" \
-     http://localhost:57374/api/enterprise/rbac/check
-
-# Response:
-{
-  "role": "operator",
-  "scopes": ["control", "read", "write"],
-  "permissions": {
-    "can_start_session": true,
-    "can_stop_session": true,
-    "can_create_tasks": true,
-    "can_modify_config": false,
-    "can_manage_tokens": false
-  }
-}
+# Succeeds only if the token carries the route's required scope
+curl -i -H "Authorization: Bearer $LOKI_TOKEN" \
+     http://localhost:57374/api/status
 ```
 
+Scope implication is resolved by `has_scope()` in `dashboard/auth.py:394`.
+
 ## Agent Action Authorization
 
-Control which roles can trigger agent actions:
-
-```yaml
-enterprise:
-  rbac:
-    agent_actions:
-      git_commit:
-        required_scope: control
-      cli_invoke:
-        required_scope: control
-      file_write:
-        required_scope: write
-      file_read:
-        required_scope: read
-```
+**Not implemented.** An earlier version of this page showed an
+`enterprise.rbac.agent_actions` block mapping individual agent actions
+(`git_commit`, `cli_invoke`, `file_write`, `file_read`) to required scopes. No
+such configuration is read by any code. Scope enforcement happens at the
+dashboard API boundary only, per route, not per agent action.
 
 ## Environment Variables
 
+These are the variables actually read by `dashboard/auth.py`. There is no
+`LOKI_RBAC_ENABLED`, `LOKI_RBAC_STRICT_MODE`, or `LOKI_RBAC_AUDIT_CHECKS`; an
+earlier version of this page listed all three and they were never implemented.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `LOKI_RBAC_ENABLED` | `false` | Enable RBAC system |
-| `LOKI_RBAC_DEFAULT_ROLE` | `viewer` | Default role for OIDC users |
-| `LOKI_RBAC_STRICT_MODE` | `false` | Deny access when role is undefined (vs default to viewer) |
-| `LOKI_RBAC_AUDIT_CHECKS` | `true` | Log all permission checks to audit log |
+| `LOKI_ENTERPRISE_AUTH` | `false` | Enable token authentication |
+| `LOKI_OIDC_ISSUER` | (empty) | OIDC issuer URL; set with `LOKI_OIDC_CLIENT_ID` to enable OIDC/SSO |
+| `LOKI_OIDC_CLIENT_ID` | (empty) | OIDC client id |
+| `LOKI_OIDC_AUDIENCE` | (empty) | Expected audience; usually the same as the client id |
+| `LOKI_OIDC_ROLES_CLAIM` | (empty) | Claim to read roles from; supports a dotted path |
+| `LOKI_OIDC_DEFAULT_ROLE` | `viewer` | Role applied when no recognized role claim is present |
+
+`_scopes_from_claims()` never returns `["*"]`/admin by default: full access
+requires an explicit admin role claim. When no recognized role claim is present,
+the least-privileged default role applies.
 
 ## Examples
 
 ### Multi-Environment Setup
 
 ```bash
-# Production - strict RBAC
-export LOKI_RBAC_ENABLED=true
-export LOKI_RBAC_STRICT_MODE=true
-export LOKI_RBAC_DEFAULT_ROLE=viewer
-
-# Development - relaxed RBAC
-export LOKI_RBAC_ENABLED=false
-
-# Staging - moderate RBAC
-export LOKI_RBAC_ENABLED=true
-export LOKI_RBAC_DEFAULT_ROLE=operator
+# Production - OIDC with a least-privilege default
+export LOKI_ENTERPRISE_AUTH=true
+export LOKI_OIDC_ISSUER=https://accounts.example.com
+export LOKI_OIDC_CLIENT_ID=loki-prod
+export LOKI_OIDC_DEFAULT_ROLE=viewer
+
+# Development - auth off
+export LOKI_ENTERPRISE_AUTH=false
+
+# Staging - OIDC with a more permissive default
+export LOKI_ENTERPRISE_AUTH=true
+export LOKI_OIDC_DEFAULT_ROLE=operator
 ```
 
 ### Team-Based Access
@@ -362,7 +364,8 @@ loki enterprise token generate security-scanner \
 
 ### Auditing
 
-1. Enable `LOKI_RBAC_AUDIT_CHECKS` to log permission checks
+1. Review audit logs for authentication and authorization events (audit logging
+   is on by default; there is no separate per-permission-check toggle)
 2. Review audit logs for unauthorized access attempts
 3. Monitor for privilege escalation attempts
 4. Alert on admin role usage in production
@@ -376,8 +379,8 @@ loki enterprise token generate security-scanner \
 # Check token role and scopes
 loki enterprise token list
 
-# Verify required scope for operation
-loki enterprise rbac permissions --role <your-role>
+# Read the route's required scope from dashboard/server.py, then compare
+# against the scopes on your token from the listing above
 
 # Check audit log for denial reason
 loki enterprise audit tail --event permission.denied
@@ -406,10 +409,10 @@ loki enterprise audit tail --event auth.oidc.success
 ### Scope Confusion
 
 ```bash
-# List all scopes for a role
-loki enterprise rbac permissions --role operator
+# List the scopes actually attached to each token
+loki enterprise token list
 
-# Check if scope is implied by hierarchy
+# Check if scope is implied by hierarchy (see has_scope, dashboard/auth.py:394)
 # control -> write -> read
 # audit (separate, not included in control)
 
@@ -420,32 +423,35 @@ curl -H "Authorization: Bearer $TOKEN" \
 
 ## Migration Guide
 
-### Upgrading from Token-Only to RBAC
+### Upgrading from Token-Only to role-mapped OIDC
 
-1. Enable RBAC in audit mode first:
-```bash
-export LOKI_RBAC_ENABLED=true
-export LOKI_RBAC_STRICT_MODE=false  # Allow during migration
-```
+There is no separate "RBAC mode" to switch on, and no in-place token editing.
+`loki enterprise` has exactly three subcommands: `status`, `token`, and
+`audit`. An earlier version of this page described `loki enterprise rbac check`
+and `loki enterprise token update --role`; neither exists.
 
-2. Assign roles to existing tokens:
+1. Turn on enterprise auth and point Loki at your identity provider:
 ```bash
-for token in $(loki enterprise token list --format json | jq -r '.[].id'); do
-  loki enterprise token update $token --role operator
-done
+export LOKI_ENTERPRISE_AUTH=true
+export LOKI_OIDC_ISSUER=https://accounts.example.com
+export LOKI_OIDC_CLIENT_ID=your-client-id
+export LOKI_OIDC_DEFAULT_ROLE=viewer
 ```
 
-3. Test permissions:
+2. Re-issue tokens with the scopes each holder should have. Tokens carry scopes
+   directly and are not editable after creation, so revoke and regenerate:
 ```bash
-loki enterprise rbac check
+loki enterprise token list
+loki enterprise token generate dev-1 --scopes control,read,write --expires 30
 ```
 
-4. Enable strict mode:
+3. Confirm the configuration is active:
 ```bash
-export LOKI_RBAC_STRICT_MODE=true
+loki enterprise status
 ```
 
-5. Monitor audit logs for denials and adjust roles as needed.
+4. Monitor audit logs for denials and adjust the role claim mapping
+   (`LOKI_OIDC_ROLES_CLAIM`) as needed.
 
 ## See Also
 

package/docs/git-workflow.md

@@ -169,7 +169,7 @@ Estimated cost: $X.XX USD
 - End: YYYY-MM-DD HH:MM:SS
 - Duration: X hours
 - Iterations: X
-- Provider: claude/codex/gemini
+- Provider: claude/cline/codex/aider/opencode
 ```
 
 Set template path:
@@ -200,8 +200,11 @@ All Git operations performed by agents are logged to `.loki/logs/agent-audit.jso
 View audit log:
 
 ```bash
-loki audit log
-loki audit log --action git_commit
+loki audit log          # most recent entries (optional positional line count)
+loki audit log 200
+
+# loki audit log takes a line count, not filter flags. Filter with grep:
+loki audit log 500 | grep git_commit
 ```
 
 ## Git Hooks

package/docs/metrics.md

@@ -15,12 +15,12 @@ Loki Mode exposes a `/metrics` endpoint that returns production-ready metrics in
 
 ## Quick Start
 
-```bash
-# Enable metrics endpoint
-export LOKI_METRICS_ENABLED=true
+The `/metrics` endpoint is served by the dashboard and needs no enabling flag.
+Start the dashboard and scrape it.
 
-# Start Loki Mode
-loki start ./prd.md
+```bash
+# Start the dashboard (serves /metrics)
+loki dashboard start
 
 # View metrics
 curl http://localhost:57374/metrics
@@ -362,22 +362,21 @@ Configure alerts in Grafana panels:
 
 ## Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOKI_METRICS_ENABLED` | `false` | Enable `/metrics` endpoint |
-| `LOKI_METRICS_PORT` | `57374` | Port for metrics endpoint (same as dashboard) |
-| `LOKI_METRICS_PATH` | `/metrics` | Endpoint path |
+There are none. `/metrics` is an unconditional route on the dashboard app
+(`dashboard/server.py:9637`), served at the dashboard's own port and path. An
+earlier version of this page listed `LOKI_METRICS_ENABLED`,
+`LOKI_METRICS_PORT`, and `LOKI_METRICS_PATH`; none of the three is read by any
+code, so the endpoint cannot be turned off, moved, or re-pathed by environment.
+
+To change the port, change the dashboard port. To restrict access, put the
+dashboard behind a reverse proxy: unlike the `/api/*` routes, `/metrics` has no
+auth scope dependency, so anything that can reach the port can read it.
 
 ## Best Practices
 
 ### Production Deployment
 
-1. Enable metrics in production:
-```bash
-export LOKI_METRICS_ENABLED=true
-```
-
-2. Secure endpoint with reverse proxy authentication
+1. Secure endpoint with reverse proxy authentication
 3. Set up Prometheus scraping with appropriate interval (15-30s)
 4. Create Grafana dashboards for visualization
 5. Configure alerts for budget, stagnation, and failures

package/docs/network-security.md

@@ -8,15 +8,17 @@ This guide covers network-level security controls for restricting outbound netwo
 
 ## Environment Variables
 
-The following environment variables control network egress policy enforcement:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOKI_NETWORK_EGRESS_POLICY` | `unrestricted` | `unrestricted` (default), `ai-only` (restrict to AI APIs), `none` (block all outbound) |
-| `LOKI_ALLOWED_HOSTS` | (empty) | Comma-separated list of additional hostnames to allow when egress policy is `ai-only` |
-| `LOKI_BLOCK_METADATA_ENDPOINT` | `false` | Block cloud metadata endpoint (169.254.169.254) from within the application |
-
-Note: These variables are reserved for future application-level enforcement. Currently, network security is implemented at the infrastructure level using Docker networks or Kubernetes NetworkPolicy.
+**None of the variables below are implemented. Do not rely on them.** They are
+reserved names for a planned application-level enforcement layer, and no
+runtime code reads any of them today. Network security is enforced entirely at
+the infrastructure level, using the Docker network and Kubernetes NetworkPolicy
+recipes in the rest of this guide.
+
+| Variable | Default | Description | Status |
+|----------|---------|-------------|--------|
+| `LOKI_NETWORK_EGRESS_POLICY` | `unrestricted` | `unrestricted` (default), `ai-only` (restrict to AI APIs), `none` (block all outbound) | Planned, target TBD |
+| `LOKI_ALLOWED_HOSTS` | (empty) | Comma-separated list of additional hostnames to allow when egress policy is `ai-only` | Planned, target TBD |
+| `LOKI_BLOCK_METADATA_ENDPOINT` | `false` | Block cloud metadata endpoint (169.254.169.254) from within the application | Planned, target TBD |
 
 ## Docker Network Isolation
 
@@ -56,8 +58,10 @@ iptables -A DOCKER-USER -p tcp --dport 53 -j ACCEPT
 iptables -A DOCKER-USER -d api.anthropic.com -p tcp --dport 443 -j ACCEPT
 # OpenAI (Codex)
 iptables -A DOCKER-USER -d api.openai.com -p tcp --dport 443 -j ACCEPT
-# Google (Gemini)
-iptables -A DOCKER-USER -d generativelanguage.googleapis.com -p tcp --dport 443 -j ACCEPT
+# Add one rule per endpoint your chosen provider actually calls. Cline, Aider,
+# and opencode are model-agnostic, so their endpoints depend on your config.
+# The Gemini rule that used to sit here was removed with the provider (v7.5.18);
+# do not re-add an allowlist entry for a provider you are not running.
 
 # Drop all other outbound traffic from the isolated network
 iptables -A DOCKER-USER -s 172.28.0.0/16 -j DROP
@@ -185,8 +189,7 @@ spec:
 Enable encrypted dashboard connections:
 
 ```bash
-# Using environment variables
-export LOKI_TLS_ENABLED=true
+# HTTPS turns on when BOTH are set. There is no LOKI_TLS_ENABLED switch.
 export LOKI_TLS_CERT=/path/to/cert.pem
 export LOKI_TLS_KEY=/path/to/key.pem