loki-mode 5.51.0 → 5.52.1

package/docs/certification/02-enterprise-features/lab.md

@@ -0,0 +1,154 @@
+# Module 2 Lab: Configure Enterprise Features
+
+## Objective
+
+Enable and verify enterprise features: audit logging, OTEL observability, token authentication, and dashboard TLS.
+
+## Prerequisites
+
+- Loki Mode installed (`npm install -g loki-mode`)
+- `loki doctor` passing
+- `jq` installed for JSON inspection
+
+## Step 1: Verify Audit Logging Is Active
+
+Audit logging is enabled by default. Verify its status:
+
+```bash
+loki enterprise status
+```
+
+The output should show audit logging as enabled.
+
+Start a session briefly to generate audit entries:
+
+```bash
+# Create a minimal project directory
+mkdir -p /tmp/enterprise-lab && cd /tmp/enterprise-lab
+git init
+
+# Check audit status
+loki enterprise audit status
+```
+
+**Note:** Viewing actual audit log entries requires a running session that has performed agent actions. The audit log records actions taken during `loki start`.
+
+## Step 2: Explore Audit Configuration
+
+Review the available audit environment variables:
+
+```bash
+# These are the key audit variables:
+# LOKI_AUDIT_DISABLED=true     -- Disable audit logging
+# LOKI_AUDIT_SYSLOG_HOST       -- Enable syslog forwarding
+# LOKI_AUDIT_SYSLOG_PORT       -- Syslog port (default: 514)
+# LOKI_AUDIT_SYSLOG_PROTO      -- Syslog protocol: udp or tcp
+# LOKI_AUDIT_LEVEL             -- Minimum severity to log
+# LOKI_AUDIT_EXCLUDE_EVENTS    -- Comma-separated events to skip
+```
+
+To temporarily disable audit logging (not recommended for production):
+
+```bash
+LOKI_AUDIT_DISABLED=true loki enterprise status
+```
+
+## Step 3: Check OTEL Readiness
+
+OTEL is lazy-loaded. Verify the conditional loading behavior:
+
+```bash
+# Without OTEL endpoint -- should report no OTEL
+loki enterprise status
+
+# To enable OTEL (requires a running OTLP collector):
+# export LOKI_OTEL_ENDPOINT=http://localhost:4318
+# loki start ./prd.md
+```
+
+**Note:** Actually sending OTEL data requires a running OTLP-compatible collector (such as the OpenTelemetry Collector, Jaeger, or Grafana Tempo) on the specified endpoint.
+
+## Step 4: Generate an API Token
+
+Enable enterprise authentication and generate a token:
+
+```bash
+# Enable token auth
+export LOKI_ENTERPRISE_AUTH=true
+
+# Generate a token
+loki enterprise token generate lab-test-token
+
+# Generate with expiration
+loki enterprise token generate lab-expires --expires 7
+```
+
+**Note:** Token authentication requires the dashboard API server to be running (`loki dashboard start` or `loki serve`). Without a running server, token generation creates the token but there is no API to authenticate against.
+
+## Step 5: Start and Inspect the Dashboard
+
+```bash
+# Start the dashboard server
+loki dashboard start
+
+# Check if it is running
+loki dashboard status
+
+# Get the URL
+loki dashboard url
+
+# Open in browser (macOS/Linux)
+loki dashboard open
+```
+
+The dashboard should be accessible at `http://localhost:57374`.
+
+## Step 6: Inspect Metrics
+
+While the dashboard is running:
+
+```bash
+# View Prometheus-format metrics
+loki metrics
+```
+
+This outputs metrics in OpenMetrics format suitable for Prometheus scraping.
+
+## Step 7: Review SIEM Integration Options
+
+Read the SIEM integration documentation:
+
+```bash
+# The full guide is at docs/siem-integration.md in the Loki Mode installation
+# Key platforms supported:
+# - Splunk
+# - IBM QRadar
+# - Elastic SIEM
+# - Datadog Security Monitoring
+```
+
+To configure syslog forwarding (requires an actual syslog server):
+
+```bash
+export LOKI_AUDIT_SYSLOG_HOST=your-syslog-server.example.com
+export LOKI_AUDIT_SYSLOG_PORT=514
+export LOKI_AUDIT_SYSLOG_PROTO=tcp
+```
+
+## Verification Checklist
+
+- [ ] `loki enterprise status` shows audit logging enabled
+- [ ] You understand the difference between `LOKI_AUDIT_DISABLED` and `LOKI_ENTERPRISE_AUDIT`
+- [ ] You know which environment variable activates OTEL (`LOKI_OTEL_ENDPOINT`)
+- [ ] You can generate an enterprise token with `loki enterprise token generate`
+- [ ] `loki dashboard status` correctly reports whether the dashboard is running
+- [ ] `loki metrics` outputs Prometheus-format metrics
+
+## Cleanup
+
+```bash
+loki dashboard stop
+cd ~
+rm -rf /tmp/enterprise-lab
+unset LOKI_ENTERPRISE_AUTH
+```

package/docs/certification/02-enterprise-features/lesson.md

@@ -0,0 +1,202 @@
+# Module 2: Enterprise Features
+
+## Overview
+
+Loki Mode includes enterprise features for audit logging, observability, authentication, and SIEM integration. These features are controlled via environment variables and can be enabled incrementally.
+
+## Audit Logging
+
+Audit logging records all agent actions for compliance and forensic analysis. As of v5.38.0, audit logging is **enabled by default**. It can be disabled with `LOKI_AUDIT_DISABLED=true`.
+
+### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_AUDIT_DISABLED` | `false` | Set to `true` to disable audit logging |
+| `LOKI_ENTERPRISE_AUDIT` | `false` | Legacy variable to force audit on (superseded by default-on behavior) |
+| `LOKI_AUDIT_LOG` | `true` | Enable/disable audit log file writing |
+
+### CLI Commands
+
+The `loki audit` command provides access to the audit log:
+
+```bash
+loki audit            # Show recent audit entries
+loki audit help       # Show audit subcommands
+```
+
+The `loki enterprise` command manages enterprise features:
+
+```bash
+loki enterprise status    # Show enterprise feature status
+loki enterprise help      # Show available enterprise commands
+```
+
+### Audit Log Contents
+
+Audit entries record:
+- Timestamp of each agent action
+- Agent identity and type
+- Action taken (file read, file write, command execution, etc.)
+- Target resource (file path, endpoint, etc.)
+- Outcome (success/failure)
+
+## SIEM Integration (v5.38.0)
+
+Loki Mode can forward audit logs to enterprise SIEM systems via syslog. Supported platforms include Splunk, IBM QRadar, Elastic SIEM, Datadog Security Monitoring, and others. Full configuration details are in `docs/siem-integration.md`.
+
+### Syslog Forwarding
+
+Enable syslog forwarding by setting these environment variables:
+
+```bash
+export LOKI_AUDIT_SYSLOG_HOST=syslog.example.com
+export LOKI_AUDIT_SYSLOG_PORT=514
+export LOKI_AUDIT_SYSLOG_PROTO=udp
+
+loki start ./prd.md
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_AUDIT_SYSLOG_HOST` | (none) | Syslog server hostname or IP |
+| `LOKI_AUDIT_SYSLOG_PORT` | `514` | Syslog server port |
+| `LOKI_AUDIT_SYSLOG_PROTO` | `udp` | Protocol: `udp` or `tcp` |
+| `LOKI_SYSLOG_FACILITY` | `local0` | Syslog facility (local0-local7) |
+| `LOKI_SYSLOG_SEVERITY` | `info` | Minimum severity to forward |
+
+### Filtering
+
+Control audit log verbosity:
+
+```bash
+export LOKI_AUDIT_LEVEL=warning                           # Minimum severity
+export LOKI_AUDIT_EXCLUDE_EVENTS=api.request,api.response # Skip noisy events
+```
+
+## OpenTelemetry (OTEL) Observability
+
+Loki Mode supports OpenTelemetry for distributed tracing and metrics. OTEL is **lazy-loaded** -- it only initializes when `LOKI_OTEL_ENDPOINT` is set.
+
+### Enabling OTEL
+
+```bash
+export LOKI_OTEL_ENDPOINT=http://localhost:4318
+loki start ./prd.md
+```
+
+When OTEL is not configured, Loki Mode uses no-op stubs that add zero overhead. When enabled, it exports traces and metrics to the configured OTLP endpoint.
+
+The OTEL implementation is in `src/observability/otel.js` with a conditional loader in `src/observability/index.js`. A bridge process (`src/observability/otel-bridge.js`) can forward events from the file-based event bus to OTEL.
+
+### Prometheus Metrics
+
+The `loki metrics` command exposes Prometheus/OpenMetrics formatted metrics from the dashboard:
+
+```bash
+loki metrics          # Display all metrics
+loki metrics --help   # Show options
+```
+
+These metrics can be scraped by Prometheus or any OpenMetrics-compatible collector.
+
+## Token Authentication (Enterprise)
+
+Loki Mode supports token-based API authentication for the dashboard API server. This is opt-in and requires `LOKI_ENTERPRISE_AUTH=true`.
+
+### Enabling Authentication
+
+```bash
+export LOKI_ENTERPRISE_AUTH=true
+loki start ./prd.md
+```
+
+### Managing Tokens
+
+```bash
+# Generate a new API token
+loki enterprise token generate my-token-name
+
+# Generate with specific options
+loki enterprise token generate my-token --scopes '*' --expires 30
+```
+
+When authentication is enabled, all dashboard API requests must include a valid token.
+
+## OIDC Integration
+
+For organizations using SSO, Loki Mode supports OIDC (OpenID Connect) authentication:
+
+| Variable | Description |
+|----------|-------------|
+| `LOKI_OIDC_ISSUER` | OIDC issuer URL (e.g., `https://accounts.google.com`) |
+| `LOKI_OIDC_CLIENT_ID` | OIDC client/application ID |
+| `LOKI_OIDC_AUDIENCE` | Expected JWT audience (defaults to client_id) |
+
+These variables are documented in the `autonomy/run.sh` header. OIDC validation requires a running dashboard API server.
+
+## Dashboard
+
+The Loki Mode dashboard provides a web-based UI for monitoring sessions, viewing task queues, inspecting memory, and observing agent activity.
+
+```bash
+loki dashboard start    # Start the dashboard server
+loki dashboard stop     # Stop the dashboard server
+loki dashboard status   # Check if dashboard is running
+loki dashboard open     # Open dashboard in browser
+loki dashboard url      # Print the dashboard URL
+```
+
+The dashboard runs on port 57374 by default (`LOKI_DASHBOARD_PORT`). TLS can be enabled with:
+
+```bash
+export LOKI_TLS_CERT=/path/to/cert.pem
+export LOKI_TLS_KEY=/path/to/key.pem
+```
+
+## Security Controls
+
+Loki Mode provides several security controls for enterprise environments:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_SANDBOX_MODE` | `false` | Run in Docker sandbox for isolation |
+| `LOKI_ALLOWED_PATHS` | (all) | Comma-separated paths agents can modify |
+| `LOKI_BLOCKED_COMMANDS` | `rm -rf /` | Comma-separated blocked shell commands |
+| `LOKI_MAX_PARALLEL_AGENTS` | `10` | Limit concurrent agent spawning |
+| `LOKI_STAGED_AUTONOMY` | `false` | Require approval before execution |
+| `LOKI_PROMPT_INJECTION` | `false` | Allow prompt injection via `HUMAN_INPUT.md` (disabled by default for security) |
+
+### Docker Sandbox
+
+Run Loki Mode in an isolated Docker container:
+
+```bash
+loki sandbox start     # Start sandbox container
+loki sandbox stop      # Stop sandbox container
+loki sandbox status    # Check sandbox status
+loki sandbox shell     # Open shell in sandbox
+loki sandbox logs      # View sandbox logs
+```
+
+Or via the start command:
+
+```bash
+loki start --sandbox ./prd.md
+```
+
+## Notifications
+
+Loki Mode supports notifications to external services:
+
+```bash
+loki notify test       # Send a test notification
+loki notify slack      # Send to Slack
+loki notify discord    # Send to Discord
+loki notify webhook    # Send to a webhook URL
+loki notify status     # Check notification configuration
+```
+
+## Summary
+
+Enterprise features in Loki Mode are designed to be opt-in and incrementally adoptable. Audit logging is on by default. OTEL, SIEM integration, token authentication, and OIDC are activated through environment variables. The dashboard provides a web UI for monitoring, and Docker sandbox mode provides execution isolation.

package/docs/certification/02-enterprise-features/quiz.md

@@ -0,0 +1,93 @@
+# Module 2 Quiz: Enterprise Features
+
+Answer each question by selecting the best option (A, B, C, or D).
+
+---
+
+**Question 1:** What is the default state of audit logging in Loki Mode (v5.38.0+)?
+
+A) Disabled, must be explicitly enabled
+B) Enabled by default, can be disabled with `LOKI_AUDIT_DISABLED=true`
+C) Only enabled when running in Docker sandbox
+D) Only enabled when `LOKI_ENTERPRISE_AUDIT=true` is set
+
+---
+
+**Question 2:** Which environment variable enables OpenTelemetry in Loki Mode?
+
+A) `LOKI_OTEL_ENABLED=true`
+B) `LOKI_TELEMETRY=true`
+C) `LOKI_OTEL_ENDPOINT=http://localhost:4318`
+D) `OTEL_EXPORTER_ENDPOINT=http://localhost:4318`
+
+---
+
+**Question 3:** What is the default port for the Loki Mode dashboard?
+
+A) 3000
+B) 8080
+C) 57374
+D) 9090
+
+---
+
+**Question 4:** Which environment variable enables token-based API authentication?
+
+A) `LOKI_AUTH_ENABLED=true`
+B) `LOKI_ENTERPRISE_AUTH=true`
+C) `LOKI_TOKEN_AUTH=true`
+D) `LOKI_API_AUTH=true`
+
+---
+
+**Question 5:** What protocol options does Loki Mode support for syslog forwarding?
+
+A) HTTP and HTTPS only
+B) UDP and TCP
+C) gRPC and HTTP
+D) MQTT and AMQP
+
+---
+
+**Question 6:** What happens when `LOKI_OTEL_ENDPOINT` is NOT set?
+
+A) Loki Mode refuses to start
+B) OTEL uses a default localhost endpoint
+C) Loki Mode uses no-op stubs with zero overhead
+D) OTEL data is written to a local file
+
+---
+
+**Question 7:** Which command generates an API token for the dashboard?
+
+A) `loki auth token create`
+B) `loki enterprise token generate my-token`
+C) `loki dashboard auth --new-token`
+D) `loki config auth token`
+
+---
+
+**Question 8:** How do you enable TLS for the Loki Mode dashboard?
+
+A) Set `LOKI_DASHBOARD_TLS=true`
+B) Set `LOKI_TLS_CERT` and `LOKI_TLS_KEY` to PEM file paths
+C) Pass `--tls` flag to `loki dashboard start`
+D) TLS is always enabled by default
+
+---
+
+**Question 9:** What does `LOKI_PROMPT_INJECTION` control?
+
+A) Whether agents can execute shell commands
+B) Whether the `HUMAN_INPUT.md` file can inject directives into a running session
+C) Whether API tokens expire automatically
+D) Whether OTEL traces include prompt content
+
+---
+
+**Question 10:** Which command checks the status of all enterprise features?
+
+A) `loki config show`
+B) `loki enterprise status`
+C) `loki doctor --enterprise`
+D) `loki status --enterprise`

package/docs/certification/03-advanced-patterns/lab.md

@@ -0,0 +1,138 @@
+# Module 3 Lab: Advanced Patterns
+
+## Objective
+
+Practice structured agent prompting, explore the specialist review configuration, and examine the compound learning system.
+
+## Prerequisites
+
+- Loki Mode installed (`npm install -g loki-mode`)
+- Familiarity with Module 1 (core concepts) and Module 2 (enterprise features)
+- `jq` installed for JSON inspection
+
+## Step 1: Examine the Specialist Review Configuration
+
+Read the quality gates documentation to understand how specialists are selected:
+
+```bash
+# Locate the skill file (path depends on your installation)
+# If installed globally via npm:
+SKILL_DIR=$(npm root -g)/loki-mode
+
+# Read the specialist review pool configuration
+cat "$SKILL_DIR/skills/quality-gates.md" | head -100
+```
+
+Key points to verify:
+- 5 specialists defined with trigger keywords
+- architecture-strategist is always selected
+- Selection is based on keyword matching against the diff
+
+## Step 2: Write a Structured Agent Prompt
+
+Create a file called `structured-prompt-example.md` demonstrating the GOAL/CONSTRAINTS/CONTEXT/OUTPUT template:
+
+```markdown
+## GOAL
+Implement a rate-limiting middleware for Express.js.
+Success: Middleware limits requests to 100/minute per IP, returns 429 on excess.
+
+## CONSTRAINTS
+- No external rate-limiting libraries
+- Use in-memory storage (Map with TTL cleanup)
+- Must not block the event loop
+- Response time overhead < 5ms
+
+## CONTEXT
+- Existing middleware pattern: src/middleware/auth.ts
+- Express app entry point: src/app.ts
+- No existing rate limiting in codebase
+
+## OUTPUT
+- [ ] Middleware implementation in src/middleware/rate-limit.ts
+- [ ] Unit tests in tests/middleware/rate-limit.test.ts
+- [ ] Integration into app.ts route chain
+```
+
+This is the format used when dispatching any agent via the Task tool. Each section serves a purpose: GOAL defines success criteria, CONSTRAINTS set boundaries, CONTEXT points to relevant files, and OUTPUT lists deliverables.
+
+## Step 3: Explore Compound Learning
+
+Examine the compound learning CLI commands:
+
+```bash
+# List extracted solutions (if any exist)
+loki compound list
+
+# View statistics
+loki compound stats
+
+# Search for solutions by keyword
+loki compound search "authentication"
+```
+
+Solutions are stored in `~/.loki/solutions/{category}/{slug}.md` with YAML frontmatter containing title, tags, symptoms, root cause, and prevention guidance.
+
+**Note:** Compound learning populates over time as Loki Mode completes tasks. A fresh installation will have no solutions until sessions have run and produced novel insights.
+
+## Step 4: Examine the Memory Retrieval Weights
+
+Review how task-aware memory retrieval works. The weight configurations are in `memory/engine.py`:
+
+```bash
+SKILL_DIR=$(npm root -g)/loki-mode
+
+# View the task strategy weights
+head -60 "$SKILL_DIR/memory/engine.py"
+```
+
+You should see weight configurations like:
+
+| Task Type | Episodic | Semantic | Skills | Anti-patterns |
+|-----------|----------|----------|--------|---------------|
+| exploration | 0.6 | 0.3 | 0.1 | 0.0 |
+| implementation | 0.15 | 0.5 | 0.35 | 0.0 |
+| debugging | 0.4 | 0.2 | 0.0 | 0.4 |
+
+This demonstrates how the system prioritizes different memory types based on what the agent is currently doing.
+
+## Step 5: Understand the Event Bus
+
+Loki Mode includes an event bus for inter-component communication. Examine the event emission helper:
+
+```bash
+SKILL_DIR=$(npm root -g)/loki-mode
+
+# View the bash event emitter
+cat "$SKILL_DIR/events/emit.sh" | head -30
+```
+
+Events are emitted during operations like memory loading, session start/stop, and task completion. The dashboard and OTEL bridge consume these events for real-time monitoring.
+
+## Step 6: Review the Hooks System
+
+The hooks system runs quality checks on file operations. Review the configuration in the testing skill:
+
+```bash
+SKILL_DIR=$(npm root -g)/loki-mode
+cat "$SKILL_DIR/skills/testing.md"
+```
+
+Look for the `hooks_system` section which defines triggers for:
+- `on_file_write` -- lint, typecheck, secrets scan
+- `on_task_complete` -- contract tests, spec validation
+- `on_phase_complete` -- memory consolidation, metrics, checkpoint
+
+## Verification Checklist
+
+- [ ] You can write a structured prompt with GOAL/CONSTRAINTS/CONTEXT/OUTPUT sections
+- [ ] You understand how the 5 specialist reviewers are selected (keyword matching + architecture-strategist always included)
+- [ ] You can use `loki compound` commands to explore extracted solutions
+- [ ] You understand the task-aware memory retrieval weight system
+- [ ] You know the three hook trigger points (file write, task complete, phase complete)
+
+## Cleanup
+
+```bash
+rm -f structured-prompt-example.md
+```