loki-mode 7.46.0 → 7.48.0

package/dashboard/auth.py

@@ -477,6 +477,111 @@ def _base64url_decode(data: str) -> bytes:
     return base64.urlsafe_b64decode(data)
 
 
+# Role precedence (highest privilege first). When a token carries multiple
+# recognized role claims, the highest-privilege match wins.
+_ROLE_PRECEDENCE = ("admin", "operator", "auditor", "viewer")
+
+
+def _normalize_claim_values(value) -> set[str]:
+    """Normalize an OIDC claim value into a lowercased set of strings.
+
+    Claim values may be a single string, a space-separated string, or a
+    list of strings (different providers use different shapes). All are
+    flattened into a set of lowercased tokens for matching against ROLES.
+    """
+    out: set[str] = set()
+    if value is None:
+        return out
+    if isinstance(value, str):
+        for part in value.split():
+            if part:
+                out.add(part.strip().lower())
+    elif isinstance(value, (list, tuple, set)):
+        for item in value:
+            if isinstance(item, str):
+                s = item.strip().lower()
+                if s:
+                    out.add(s)
+    return out
+
+
+def _collect_role_claims(claims: dict) -> set[str]:
+    """Collect candidate role/group values from standard OIDC claim shapes.
+
+    Recognized sources (case-insensitive values flattened into one set):
+    - A configurable claim named by LOKI_OIDC_ROLES_CLAIM (supports a dotted
+      path for nested claims, e.g. "realm_access.roles" for Keycloak).
+    - "roles" (generic)
+    - "groups" (generic)
+    - "realm_access.roles" (Keycloak)
+    - "cognito:groups" (AWS Cognito)
+
+    Note: "groups"/"cognito:groups" typically carry arbitrary group names,
+    not Loki role names. Only values that exactly match one of the four
+    built-in role names (admin/operator/viewer/auditor, case-insensitive)
+    grant a role. Everything else is ignored and the default role applies.
+    """
+    candidates: set[str] = set()
+
+    def _read_dotted(path: str):
+        node = claims
+        for key in path.split("."):
+            if isinstance(node, dict) and key in node:
+                node = node[key]
+            else:
+                return None
+        return node
+
+    configured = os.environ.get("LOKI_OIDC_ROLES_CLAIM", "").strip()
+    sources = []
+    if configured:
+        sources.append(configured)
+    sources.extend(["roles", "groups", "realm_access.roles", "cognito:groups"])
+
+    for src in sources:
+        if "." in src:
+            val = _read_dotted(src)
+        else:
+            val = claims.get(src)
+        candidates |= _normalize_claim_values(val)
+
+    return candidates
+
+
+def _default_oidc_role() -> str:
+    """Return the configured default OIDC role, validated against ROLES.
+
+    Defaults to the least-privileged role ("viewer"). If LOKI_OIDC_DEFAULT_ROLE
+    is set to an unrecognized value, falls back to "viewer" (never admin).
+    """
+    configured = os.environ.get("LOKI_OIDC_DEFAULT_ROLE", "").strip().lower()
+    if configured in ROLES:
+        return configured
+    return "viewer"
+
+
+def _scopes_from_claims(claims: dict) -> tuple[list[str], str]:
+    """Map OIDC token claims to Loki scopes via the existing ROLES mapping.
+
+    Returns a tuple of (scopes, role_name). If no recognized role claim is
+    present, the safe default role (viewer, or LOKI_OIDC_DEFAULT_ROLE) is
+    applied. This function NEVER returns ["*"]/admin by default: full access
+    is granted only when an explicit admin role claim is present.
+    """
+    candidate_values = _collect_role_claims(claims)
+
+    matched_role = None
+    for role in _ROLE_PRECEDENCE:
+        if role in candidate_values:
+            matched_role = role
+            break
+
+    if matched_role is None:
+        matched_role = _default_oidc_role()
+
+    return resolve_scopes(matched_role), matched_role
+
+
 def validate_oidc_token(token_str: str) -> Optional[dict]:
     """Validate an OIDC JWT token.
 
@@ -489,6 +594,12 @@ def validate_oidc_token(token_str: str) -> Optional[dict]:
     - Audience matches OIDC_AUDIENCE or OIDC_CLIENT_ID
     - Token is not expired
 
+    On success, role/group claims are mapped to Loki roles (admin/operator/
+    viewer/auditor) via _scopes_from_claims. When no recognized role claim is
+    present, the least-privileged default role (viewer, configurable via
+    LOKI_OIDC_DEFAULT_ROLE) is applied. OIDC users are never granted ["*"]
+    unless an explicit admin role claim is present.
+
     SECURITY CRITICAL: Without PyJWT, JWT signatures are NOT cryptographically
     verified. An attacker can forge tokens with arbitrary claims. For any
     production deployment, you MUST install PyJWT + cryptography so that
@@ -529,11 +640,13 @@ def validate_oidc_token(token_str: str) -> Optional[dict]:
             issuer=OIDC_ISSUER,
         )
 
+        scopes, role = _scopes_from_claims(decoded)
         return {
             "id": decoded.get("sub", ""),
             "name": decoded.get("name", decoded.get("email", decoded.get("sub", ""))),
             "email": decoded.get("email", ""),
-            "scopes": ["*"],  # OIDC users get full access
+            "scopes": scopes,  # mapped from OIDC role/group claims
+            "role": role,
             "auth_method": "oidc",
             "issuer": decoded.get("iss"),
         }
@@ -602,11 +715,13 @@ def validate_oidc_token(token_str: str) -> Optional[dict]:
             return None
 
         # Return user info from claims
+        scopes, role = _scopes_from_claims(claims)
         return {
             "id": claims.get("sub", ""),
             "name": claims.get("name", claims.get("email", claims.get("sub", ""))),
             "email": claims.get("email", ""),
-            "scopes": ["*"],  # OIDC users get full access
+            "scopes": scopes,  # mapped from OIDC role/group claims
+            "role": role,
             "auth_method": "oidc",
             "issuer": claims.get("iss"),
         }

package/dashboard/telemetry.py

@@ -1,6 +1,13 @@
 """Anonymous usage telemetry for Loki Mode dashboard.
 
-Opt-out: LOKI_TELEMETRY_DISABLED=true or DO_NOT_TRACK=1
+Collection is OPT-IN and OFF by default. Nothing is sent unless the user
+explicitly opts in, so a default install (including air-gapped, GDPR, and
+FedRAMP deployments) never phones home.
+
+Opt-in (one required): LOKI_TELEMETRY=on  OR  ~/.loki/config: TELEMETRY_ENABLED=true
+Opt-out (always wins): LOKI_TELEMETRY=off / LOKI_TELEMETRY_DISABLED=true /
+                       DO_NOT_TRACK=1 / ~/.loki/config: TELEMETRY_DISABLED=true
+
 All calls are fire-and-forget, silent on failure, non-blocking.
 """
 
@@ -19,10 +26,20 @@ _POSTHOG_KEY = "phc_ya0vGBru41AJWtGNfZZ8H9W4yjoZy4KON0nnayS7s87"
 
 
 def _is_enabled():
-    # Unified opt-out: these checks must mirror loki_collection_enabled in
-    # autonomy/crash.sh so one switch gates BOTH PostHog usage telemetry and
-    # crash reporting.
-    if os.environ.get("LOKI_TELEMETRY", "").lower() == "off":
+    # Unified OPT-IN gate. Collection is OFF by default; enabled ONLY when the
+    # user has opted in AND has not also opted out. This precedence MUST mirror
+    # loki_collection_enabled in autonomy/crash.sh and _loki_telemetry_enabled
+    # in autonomy/telemetry.sh so one model gates BOTH PostHog usage telemetry
+    # and crash reporting.
+    #
+    # Precedence:
+    #   1. Any opt-out flag present  -> False (hard kill, always wins)
+    #   2. Else any opt-in flag present -> True
+    #   3. Else (default)            -> False (no egress)
+    telem = os.environ.get("LOKI_TELEMETRY", "").lower()
+
+    # --- 1. Opt-out always wins ---
+    if telem == "off":
         return False
     if os.environ.get("LOKI_TELEMETRY_DISABLED") == "true":
         return False
@@ -30,15 +47,26 @@ def _is_enabled():
         return False
     # Persistent opt-out in ~/.loki/config (matches the bash grep prefix
     # semantics: any line beginning with TELEMETRY_DISABLED=true).
+    config_enabled = False
     try:
         config_path = Path.home() / ".loki" / "config"
         if config_path.is_file():
             for line in config_path.read_text().splitlines():
                 if line.startswith("TELEMETRY_DISABLED=true"):
                     return False
+                if line.startswith("TELEMETRY_ENABLED=true"):
+                    config_enabled = True
     except Exception:
         pass
-    return True
+
+    # --- 2. Opt-in required to enable ---
+    if telem == "on":
+        return True
+    if config_enabled:
+        return True
+
+    # --- 3. Default: OFF ---
+    return False
 
 
 def _get_distinct_id():

package/docs/ACKNOWLEDGEMENTS.md

@@ -336,7 +336,7 @@ Based on research synthesis, the following improvements are planned:
 
 This acknowledgements file documents the research and resources that influenced Loki Mode's design. All referenced works retain their original licenses and copyrights.
 
-Loki Mode itself is released under the MIT License.
+Loki Mode itself is released under the Business Source License 1.1 (BUSL-1.1), a source-available license.
 
 ---
 

package/docs/COMPETITIVE-ANALYSIS.md

@@ -45,7 +45,7 @@ GSD is the closest competitor -- a context engineering system that spawns fresh
 | **Enterprise Security** | `--dangerously-skip-permissions` | MCP sandboxed | Sandboxed | Audit logs, RBAC | Staged autonomy | Sandboxed |
 | **Cross-Project Learning** | No | AgentDB | No | No | No | Limited |
 | **Observability** | Dashboard + STATUS.txt | Real-time tracing | Logs | Full tracing | Built-in | Full |
-| **Pricing** | Free (OSS) | Free (OSS) | Free (OSS) | $25+/mo | $20-400/mo | $20-500/mo |
+| **Pricing** | Free (source-available) | Free (OSS) | Free (OSS) | $25+/mo | $20-400/mo | $20-500/mo |
 | **Production Ready** | Experimental | Production | Production | Production | Production | Production |
 | **Resource Monitoring** | Yes (v2.18.5) | Unknown | No | No | No | No |
 | **State Recovery** | Yes (checkpoints) | Yes (AgentDB) | Limited | Yes | Git worktrees | Yes |

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.46.0
+**Version:** v7.48.0
 
 ---
 
@@ -114,11 +114,18 @@ faster routed commands and forward-compat with v8.0.0.
 - Installs the `loki` CLI binary to your PATH (`bin/loki` shim)
 - Subsequent `loki setup-skill` creates symlinks at `~/.claude/skills/loki-mode`, `~/.codex/skills/loki-mode`
 
-**Opt out of anonymous install telemetry:**
+**Anonymous telemetry is OPT-IN and OFF by default.** A default `npm install`
+sends nothing, so air-gapped and enterprise installs are safe out of the box. To
+opt in to anonymous diagnostics, run `loki telemetry on` or set
+`LOKI_TELEMETRY=on`. To make opting in impossible across a fleet, bake an
+opt-out into your base image (opt-out always wins):
 ```bash
+# Hard-disable everywhere (belt and suspenders; opt-out always wins):
 LOKI_TELEMETRY_DISABLED=true npm install -g loki-mode
 # Or set DO_NOT_TRACK=1
 ```
+See [PRIVACY.md](./PRIVACY.md) for the exact data sent and the full opt-in /
+opt-out model.
 
 **Update:** `npm update -g loki-mode`
 
@@ -389,7 +396,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.46.0 start ./my-spec.md
+  asklokesh/loki-mode:7.48.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/docs/OPEN-CORE-BOUNDARY.md

@@ -1,15 +1,16 @@
 # Loki Mode open-core boundary
 
-Loki Mode is and stays open source. This document draws the line between what is
-free forever and what hosted/paid/enterprise plans would add on top. R9 ships
+Loki Mode is and stays source-available (BUSL-1.1) and free to self-host. This
+document draws the line between what is free forever and what
+hosted/paid/enterprise plans would add on top. R9 ships
 the SEAMS for that line; it does not ship a hosted backend, a license server, or
 any paywall on existing functionality.
 
 ## Principle
 
-OSS is fully functional with zero hosted backend. Every capability Loki has
-today runs locally, free, with no account, no license key, and no network call
-to any Loki service. Hosted/paid features are ADDITIVE convenience and
+The free self-hosted tier is fully functional with zero hosted backend. Every
+capability Loki has today runs locally, free, with no account, no license key,
+and no network call to any Loki service. Hosted/paid features are ADDITIVE convenience and
 team/enterprise layers, never a removal or gating of something that is free
 today.
 

package/docs/P2-SPEC-ROBUSTNESS-PLAN.md

@@ -0,0 +1,192 @@
+# P2 Spec Robustness Plan (P2-1 spec interrogation gate + P2-2 assumption ledger)
+
+Status: design for implementation. No version bump, no commit in this arc.
+
+## Goal
+
+Loki must stay accurate even when the input spec is WRONG, ambiguous, or
+incomplete. Today two building blocks already detect spec defects but neither
+feeds the autonomous loop:
+
+- `autonomy/grill.sh` invokes the provider once with a Devil's-Advocate prompt
+  and writes 10-15 hardest spec questions to `.loki/grill/report.md`. It is
+  CLI-only (`grep grill autonomy/run.sh` = 0 invocations) and nothing reads its
+  output.
+- `autonomy/prd-analyzer.py` detects missing PRD dimensions and has a
+  deterministic `_make_assumption()` map, writing `.loki/prd-observations.md`,
+  which nothing reads. Its interactive Q&A is inert in non-TTY (autonomous) runs.
+
+The fix: run interrogation automatically in DISCOVERY, classify the findings,
+record every spec gap as a first-class ASSUMPTION in a tracked ledger, BLOCK
+completion while high-severity assumptions are unconfirmed-and-unacknowledged,
+and surface the ledger in the proof-of-done output. Defects are SURFACED as
+recorded assumptions, never silently autocorrected.
+
+## Core design decision: auto-acknowledgment lifecycle (prevents the trap)
+
+A naive "block completion while any high-severity assumption is unconfirmed"
+hard-blocks EVERY ambiguous run to max-iterations, because in autonomous
+(non-TTY) mode no human can ever set `confirmed=yes`. We never reach the
+"done, plus here is what I assumed" output the goal demands.
+
+Resolution: split the gate from the lifecycle.
+
+- The gate `council_assumption_ledger_gate` is a PURE function of ledger state.
+  It blocks iff an entry has `severity=high AND confirmed=false AND
+  acknowledged=false`.
+- The auto-acknowledgment lifecycle lives in run.sh (NOT in the gate). Once an
+  assumption has been written into the ledger AND injected into the build prompt
+  at least once, run.sh marks it `acknowledged=true`. Default-on; opt-out
+  `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1` keeps a human-in-the-loop path where only
+  `confirmed=true` clears the block.
+
+This is the OPPOSITE of silent autocorrect: the assumption is recorded,
+injected into the agent's prompt, and surfaced in proof-of-done. Acknowledgment
+records "Loki has SEEN this gap and proceeded with a stated default", not "Loki
+hid it". The gate still has teeth on the first iteration (high-sev unacknowledged
+blocks) and in the require-confirm path.
+
+## Severity rule (deterministic, no LLM)
+
+grill emits no severity. Classify by section / keyword on the read side:
+
+- HIGH: security blind spots; scale/reliability blind spots; missing or
+  untestable acceptance criteria; any line containing contradiction keywords
+  (contradict, conflict, inconsistent, mutually exclusive).
+- MEDIUM: ambiguities; unstated assumptions; underspecified behavior; all
+  prd-analyzer missing-dimension assumptions.
+
+This guarantees a HIGH tier exists (so the gate has teeth) and is fully
+deterministic (so tests are reproducible).
+
+## Taxonomy mapping (classification, read-side only)
+
+grill section -> finding class:
+- "Ambiguities and missing acceptance criteria" -> ambiguous (HIGH if the line
+  references acceptance criteria / testable / measurable; else MEDIUM)
+- "Unstated assumptions" -> underspecified (MEDIUM)
+- "Security blind spots" -> missing (HIGH)
+- "Scale and reliability blind spots" -> missing (HIGH)
+- any line with a contradiction keyword (any section) -> contradictory (HIGH)
+- prd-analyzer missing dimensions -> missing (MEDIUM, deterministic default)
+
+"None identified." lines are skipped (no fabricated findings).
+
+grill output contract is NOT changed (it is parsed by the loki-grill skill).
+We classify a COPY of its markdown; grill.sh stays byte-identical.
+
+## No-fabrication rule for ledger content
+
+A grill finding is a QUESTION, not a resolution. The ledger `assumption` field
+for a grill-derived gap is an honest "spec gives no answer; proceeding with the
+implementer default for <area>" plus `affects=<area>`. We do NOT invent a
+specific resolution the build will not actually follow. prd-analyzer assumptions
+reuse its existing deterministic `_make_assumption()` text verbatim.
+
+## Ledger schema (`.loki/assumptions/`)
+
+One JSON file per assumption: `.loki/assumptions/<id>.json`, plus a
+human-readable `.loki/assumptions/ledger.md` rollup regenerated on each write.
+Each entry:
+
+```json
+{
+  "id": "a-0001",
+  "gap": "<the spec defect / unanswered question, verbatim>",
+  "assumption": "<honest stated default Loki proceeds with>",
+  "why": "<why this assumption / where the gap came from: grill|prd-analyzer>",
+  "severity": "high|medium",
+  "class": "ambiguous|contradictory|underspecified|missing",
+  "affects": "<area, e.g. security, acceptance-criteria, data-model>",
+  "source": "grill|prd-analyzer",
+  "confirmed": false,
+  "acknowledged": false,
+  "created_at": "<iso8601>"
+}
+```
+
+Stable id = `a-` + zero-padded counter over existing files (idempotent: a second
+DISCOVERY run with the same findings does not duplicate; dedupe on the `gap`
+text hash).
+
+## Build surface (files + functions)
+
+1. NEW `autonomy/spec-interrogation.sh` (sourced by run.sh; standalone-testable):
+   - `spec_interrogation_classify_report <report.md path>`: pure classifier.
+     Reads grill markdown, emits one TSV/JSON finding per question line with
+     class + severity. Takes a file so a fixture report drives the test with no
+     `claude` call.
+   - `spec_interrogation_severity_for <section> <line>`: deterministic severity.
+   - `spec_ledger_write <gap> <assumption> <why> <severity> <class> <affects>
+     <source>`: idempotent writer (dedupe on gap hash) -> `.loki/assumptions/`.
+   - `spec_ledger_rebuild_md`: regenerate `.loki/assumptions/ledger.md`.
+   - `spec_ledger_high_unresolved_count`: count entries with
+     `severity=high AND confirmed=false AND acknowledged=false` (gate input;
+     also reused by the summary).
+   - `spec_ledger_acknowledge_all`: set `acknowledged=true` on all entries
+     (auto-ack lifecycle helper; default path).
+   - `spec_interrogation_run <spec_path>`: orchestrator. Default-on
+     (`LOKI_SPEC_GRILL=0` opts out). Provider-aware: source grill.sh, call
+     `grill_check_provider`; if provider absent, log honest message, skip the
+     grill subcall (NO fabricated questions), but STILL fold prd-analyzer
+     missing-dimension assumptions into the ledger so degrade surfaces something
+     non-blocking. On provider present: run `grill_main` (writes report.md),
+     classify it, write ledger entries. Always non-fatal to the run.
+
+2. `autonomy/run.sh` DISCOVERY (~13056, after prd-analyzer + council_init,
+   before the iteration loop): source spec-interrogation.sh and call
+   `spec_interrogation_run "$prd_path"`. This is the grep-able grill invocation
+   the task requires. Best-effort (`|| true`), never blocks startup.
+
+3. `autonomy/run.sh` auto-ack lifecycle: after the build prompt is constructed
+   each iteration (assumptions are injected into the prompt via build_prompt),
+   call `spec_ledger_acknowledge_all` UNLESS
+   `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1`. Inject the high-severity assumption
+   list into the build prompt (so the agent sees the gaps it must respect).
+
+4. `autonomy/completion-council.sh` `council_assumption_ledger_gate` (new),
+   slotted into `council_evaluate` right after `council_evidence_gate`
+   (mirrors 2510-2513). Same defensive `COUNCIL_STATE_DIR` default, opt-out
+   `LOKI_ASSUMPTION_GATE=0`. Blocks iff `spec_ledger_high_unresolved_count > 0`.
+   Writes `.loki/council/assumption-block.json` on block, removes it on pass.
+   Also wired into the completion-promise route in run.sh (~14525 pattern) and
+   the code_review gate chain (~15013) so the promise path cannot bypass it.
+
+5. `autonomy/run.sh` `build_completion_summary` (~2637): emit an
+   "Assumptions recorded: N (M high-severity)" block into COMPLETION.txt and the
+   ledger list, plus the count into completion.json. So "done" means "done, plus
+   here are the N places your spec was ambiguous and what I assumed."
+
+6. NEW `tests/test-spec-interrogation.sh` (bash convention, ok/bad counters,
+   source the module, mktemp fixtures):
+   - (a) classifier on a fixture grill report writes classified findings to the
+     ledger (ambiguous/contradictory/underspecified/missing + high/medium).
+   - (b) a ledger with one high/confirmed:false/acknowledged:false entry makes
+     `council_assumption_ledger_gate` return 1 (BLOCK) and write
+     assumption-block.json.
+   - (c) clean spec (no high-sev entries, or all acknowledged) -> gate returns 0
+     (no spurious block), no block file.
+   - (d) no provider -> `spec_interrogation_run` degrades cleanly: honest
+     message, prd-analyzer assumptions still folded (medium, non-blocking), run
+     proceeds, gate passes.
+
+## Gate reachability (resolved open question)
+
+The existing gates fire from THREE sites: `council_evaluate` (~2510), the
+completion-promise route (~14525), and the code_review gate chain (~15013). The
+new gate is wired into all three so high-sev unacknowledged assumptions cannot
+slip through the promise path.
+
+## Opt-out knobs (all default-on, intelligent)
+
+- `LOKI_SPEC_GRILL=0` -> skip interrogation entirely.
+- `LOKI_ASSUMPTION_GATE=0` -> gate is pass-through.
+- `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1` -> require human `confirmed=true`
+  (disables auto-ack); the human-in-the-loop path.
+
+No "user must decide the type" knob. Classification + severity are automatic.
+
+## Constraints
+
+No emojis, no em dashes, no version bump, no commit, no push. Provider-aware,
+degrade cleanly, no fabricated questions when provider absent.

package/docs/PRIVACY.md

@@ -6,14 +6,21 @@ match the code, the code is the bug; please open an issue.
 
 ## Summary
 
-- Loki Mode collects anonymous diagnostics to help find and fix bugs.
-- It NEVER collects your code, prompts, PRDs, file paths, environment values,
-  API keys, repository names, emails, or IP addresses.
-- In this version (crash reporting Phase 0), NOTHING is sent automatically.
-  Crash reports are written to a local directory only, so you can inspect
-  exactly what a future version would send.
-- You can opt out at any time with a single switch. The same switch also
-  disables the existing anonymous usage telemetry described below.
+- Anonymous diagnostics are OPT-IN and OFF by default. A default install sends
+  no telemetry or diagnostics of any kind. This covers a default `npm install`,
+  the CLI (session and command events), the dashboard, and the welcome page
+  form. Air-gapped, GDPR, and FedRAMP deployments are safe out of the box: an
+  untouched install sends us no telemetry or diagnostics. (This statement scopes
+  to telemetry and diagnostics; provider CLIs you configure, such as Claude or
+  Codex, make their own network calls under your own credentials and are
+  governed by their vendors.)
+- When you DO opt in, Loki Mode collects anonymous diagnostics to help find and
+  fix bugs. It NEVER collects your code, prompts, PRDs, file paths, environment
+  values, API keys, repository names, emails, or IP addresses.
+- Crash reporting (Phase 0) is local-only with zero network egress regardless,
+  and is also gated by opt-in, so a default install writes nothing at all.
+- You opt in with a single switch (`loki telemetry on` or `LOKI_TELEMETRY=on`)
+  and can opt back out at any time. Opt-out always wins over opt-in.
 
 ## Two collection paths exist
 
@@ -39,17 +46,35 @@ Phase 0 behavior:
     GitHub issue URL so you can submit it manually if you choose. Loki Mode does
     not submit anything for you in this version.
 
-### 2. Usage telemetry (existing, anonymous)
+### 2. Usage telemetry (anonymous, opt-in)
 
-Loki Mode already ships anonymous usage telemetry via PostHog. This predates the
-crash-reporting feature and is disclosed here for completeness.
+Loki Mode can send anonymous usage telemetry via PostHog, but ONLY after you opt
+in. By default it is OFF and nothing is sent.
 
-- Events: `session_start`, `session_end`, and an install-time event.
-- These are anonymous and gated by the same opt-out described below.
-- They never carry your code, prompts, paths, keys, or repository names.
+- Endpoint: `https://us.i.posthog.com/capture/` (override with
+  `LOKI_TELEMETRY_ENDPOINT`). The PostHog project key is a public ingest key.
+- Events: `install` (on `npm install`), `session_start`, `session_end`,
+  `cli_command`, and `dashboard_start`.
+- Exact payload (every event): `os` (uname system), `arch` (CPU arch),
+  `version` (Loki Mode version), `channel` (npm / docker / homebrew / skill /
+  source), and a random per-machine `distinct_id` (a uuid4 stored in
+  `~/.loki-telemetry-id`, never an email or name). The `install` event also adds
+  `node_version` and `providers_installed` (which provider CLIs were detected,
+  e.g. "claude,codex"). Some events add a small free-of-PII property such as the
+  command name. No code, prompts, paths, keys, repo names, emails, or IPs.
 
-This document and the first-run notice describe BOTH paths. The opt-out is
-unified: one switch disables crash reporting AND usage telemetry together.
+### 3. Welcome page form (anonymous, explicit submit, opt-in)
+
+The `loki welcome` page (`assets/welcome/welcome.html`) shows an optional form.
+It NEVER sends anything on page load and is rendered inert unless you have opted
+in. If you have opted in AND you choose to fill in and submit the form, it sends
+these additional self-reported fields to PostHog: your role, company size, and
+the tools you use, plus the same anonymous `distinct_id`. It still never sends
+your name, email, or IP. In headless / Docker / CI environments there is no
+browser, so this path never runs.
+
+This document and the first-run notice describe ALL paths. The model is unified:
+one opt-in enables them and one opt-out (which always wins) disables them.
 
 ## What is collected (the whitelist)
 
@@ -90,17 +115,46 @@ prompts, briefs, and diffs can never reach the payload even if a redaction rule
 were to miss something. Secrets are additionally scrubbed by the shared redactor
 before whitelisting.
 
-## How to opt out
+## How to opt in (and opt back out)
+
+Collection is OFF by default. To turn it on, use ANY one of:
 
-Any one of the following disables BOTH crash reporting and usage telemetry:
+- Run `loki telemetry on` (persists `TELEMETRY_ENABLED=true` to `~/.loki/config`)
+- Set the environment variable `LOKI_TELEMETRY=on` (exact word `on`,
+  case-insensitive; values like `1` or `true` do NOT count as consent)
+
+To opt back out at any time, use ANY one of the following. Opt-out always wins
+over opt-in, so setting one of these guarantees nothing is collected or sent:
 
-- Set the environment variable `LOKI_TELEMETRY=off`
 - Run `loki telemetry off`
+- Set `LOKI_TELEMETRY=off`
 - Set `DO_NOT_TRACK=1` (the cross-tool community convention)
 - Set `LOKI_TELEMETRY_DISABLED=true`
 
-To re-enable later, run `loki telemetry on` or unset the variables. Once you opt
-out, the first-run notice is never shown again.
+### Precedence (exact)
+
+1. If any opt-out flag is set, collection is OFF (hard kill, always wins).
+2. Else if any opt-in flag is set, collection is ON.
+3. Otherwise (the default), collection is OFF.
+
+### Air-gapped and enterprise deployments
+
+Because collection is opt-in, a default install in an air-gapped, GDPR, or
+FedRAMP environment sends us no telemetry or diagnostics: there is nothing to
+turn off because there is nothing on. To make opting in impossible by accident
+across a fleet, bake `LOKI_TELEMETRY_DISABLED=true` (or `DO_NOT_TRACK=1`) into
+your base image or CI environment; opt-out always wins regardless of any later
+opt-in.
+
+This same gate covers ALL paths: the `npm install` event, CLI session and
+command events, the dashboard event, the welcome form, and local crash capture.
+
+### OpenTelemetry (separate, self-hosted)
+
+`loki telemetry enable [endpoint]` and `LOKI_OTEL_ENDPOINT` configure optional
+OpenTelemetry tracing to an endpoint YOU run. There is no default endpoint, so
+this never egresses to us; it is opt-in by definition and points only where you
+tell it to.
 
 ## Where reports are stored locally
 
@@ -129,12 +183,16 @@ that choice plainly so you can decide whether to opt out.
 
 ## Compliance posture
 
+- Opt-in by default: nothing is collected or sent unless the user explicitly
+  opts in. A default install (including air-gapped) sends us no telemetry or
+  diagnostics.
 - Anonymous by design: no PII is in the whitelist; emails and IP addresses are
-  denied outright.
+  denied outright. The welcome form's role / company-size / tools fields are
+  self-reported and anonymous (no name, email, or IP).
 - Disclosed: this document plus a first-run notice describe collection before
   any egress occurs.
-- Opt-out is persistent and friction-free (see above) and applies to both
-  collection paths.
+- Opt-out is persistent, friction-free, and ALWAYS wins over opt-in. It applies
+  to every collection path.
 - The project id is non-reversible (one-way hash).
 - Deletion: you can delete local reports yourself by removing files under
   `.loki/crash/`.

package/docs/R9-OPEN-CORE-HOOKS-PLAN.md

@@ -3,8 +3,8 @@
 Status: SEAMS implemented (this worktree). NOT a live hosted backend.
 
 R9 in the competitive-stickiness arc is the open-core monetization layer: keep
-Loki fully open source and free, while adding the SEAMS where hosted, enterprise,
-and paid plans would attach later. R9 ships the seams only. There is no Loki
+Loki fully source-available (BUSL-1.1) and free to self-host, while adding the
+SEAMS where hosted, enterprise, and paid plans would attach later. R9 ships the seams only. There is no Loki
 hosted service, no license-verification backend, and no paid gate on any
 existing feature. Every honest stub is labeled as such.