docs: add offline quickstart smoke proof

.gitignore

@@ -175,6 +175,7 @@ Gradata/scripts/*
 !Gradata/scripts/publish-npm.sh
 !Gradata/scripts/cloud/
 !Gradata/scripts/migrate_legacy_scopes.py
+!Gradata/scripts/smoke_quickstart.py
 
 # npm sub-package build outputs (source tracked, outputs ignored)
 Gradata/packages/npm/node_modules/

Gradata/README.md

@@ -106,6 +106,14 @@ gradata install --agent claude-code --brain ./my-brain
 gradata audit
 ```
 
+Want to prove the SDK/CLI path first, without Cloud sync, API keys, or a daemon? From a checkout, run:
+
+```bash
+python3 scripts/smoke_quickstart.py
+```
+
+The smoke script creates a temporary local brain, records one correction, recalls rules, and renders a manifest using only stdlib + the local package.
+
 Supported agent targets:
 
 ```bash

Gradata/docs/getting-started/quickstart.md

@@ -2,6 +2,16 @@
 
 Get a brain learning from your corrections in under 5 minutes.
 
+## 0. Optional: prove the local quickstart works offline
+
+Before connecting Cloud sync, agent hooks, or API keys, run the repo smoke test:
+
+```bash
+python3 scripts/smoke_quickstart.py
+```
+
+It creates a temporary local brain, records one correction, recalls rules, renders a manifest, and exits without network credentials or a daemon. This is the fastest pre-Hacker News proof that the SDK/CLI path works on your machine.
+
 ## 1. Create a Brain
 
 ```python

Gradata/scripts/smoke_quickstart.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Offline quickstart smoke test for Show HN/readme proof.
+
+This intentionally uses only the local SDK/CLI path:
+- no Gradata Cloud key
+- no daemon requirement
+- no network calls
+- no LLM/provider credentials
+
+Run from a checkout:
+    python3 scripts/smoke_quickstart.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+
+def _run(args: list[str], *, cwd: Path, env: dict[str, str]) -> subprocess.CompletedProcess[str]:
+    result = subprocess.run(
+        args,
+        cwd=cwd,
+        env=env,
+        text=True,
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+    if result.returncode != 0:
+        cmd = " ".join(args)
+        raise RuntimeError(
+            f"command failed ({result.returncode}): {cmd}\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}\n"
+        )
+    return result
+
+
+def smoke(tmp_root: Path) -> dict[str, object]:
+    brain_dir = tmp_root / "show-hn-brain"
+    home_dir = tmp_root / "home"
+    home_dir.mkdir()
+
+    env = os.environ.copy()
+    env.update(
+        {
+            "HOME": str(home_dir),
+            "PYTHONPATH": str(SRC),
+            "GRADATA_TELEMETRY": "0",
+            "GRADATA_DISABLE_WRITE_THROUGH": "1",
+            "GRADATA_BRAIN": str(brain_dir),
+        }
+    )
+    env.pop("GRADATA_API_KEY", None)
+    env.pop("ANTHROPIC_API_KEY", None)
+    env.pop("OPENAI_API_KEY", None)
+    env.pop("GOOGLE_API_KEY", None)
+
+    py = sys.executable
+    commands = [
+        [
+            py,
+            "-m",
+            "gradata.cli",
+            "init",
+            str(brain_dir),
+            "--domain",
+            "Sales",
+            "--name",
+            "Show HN Smoke Brain",
+            "--no-interactive",
+        ],
+        [
+            py,
+            "-m",
+            "gradata.cli",
+            "--brain-dir",
+            str(brain_dir),
+            "correct",
+            "--draft",
+            "We are pleased to inform you of our new product offering.",
+            "--final",
+            "Hey, check out what we just shipped.",
+            "--category",
+            "tone",
+            "--session",
+            "1",
+        ],
+        [py, "-m", "gradata.cli", "--brain-dir", str(brain_dir), "recall", "draft a launch email"],
+        [py, "-m", "gradata.cli", "--brain-dir", str(brain_dir), "manifest", "--json"],
+        [py, "-m", "gradata.cli", "--brain-dir", str(brain_dir), "stats"],
+    ]
+
+    outputs: list[str] = []
+    for cmd in commands:
+        result = _run(cmd, cwd=ROOT, env=env)
+        outputs.append(result.stdout.strip())
+
+    manifest = json.loads(outputs[3])
+    system_db = brain_dir / "system.db"
+    if not system_db.exists():
+        raise AssertionError(f"expected local brain database at {system_db}")
+
+    return {
+        "brain_dir": str(brain_dir),
+        "database_created": system_db.exists(),
+        "sessions_trained": manifest.get("metadata", {}).get("sessions_trained"),
+        "commands": [" ".join(cmd) for cmd in commands],
+    }
+
+
+def main() -> int:
+    keep = os.environ.get("GRADATA_SMOKE_KEEP_TMP") == "1"
+    tmp_root = Path(tempfile.mkdtemp(prefix="gradata-quickstart-smoke-"))
+    try:
+        result = smoke(tmp_root)
+        print("Gradata offline quickstart smoke: PASS")
+        print(json.dumps(result, indent=2))
+        return 0
+    finally:
+        if keep:
+            print(f"kept temp dir: {tmp_root}")
+        else:
+            shutil.rmtree(tmp_root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Gradata/src/gradata/cli.py

@@ -518,17 +518,18 @@ def _cmd_install_agent(args) -> None:
                     verification_dir = Path(verification_tmp) / "brain"
                     Brain.init(verification_dir)
                     verification_brain = Brain(verification_dir)
-                    correction = verification_brain.correct(
+                    verification_brain.correct(
                         draft=f"test draft for {name} install verification {verification_marker}",
                         final=f"test final for {name} install verification {verification_marker}",
                         dry_run=False,
                     )
-                    results = verification_brain.search(verification_marker, mode="rules", top_k=3)
+                    events = verification_brain.query_events(event_type="CORRECTION", limit=10)
                     marker_found = any(
-                        verification_marker in (r.get("text") or "").lower() for r in results
+                        verification_marker in json.dumps(event.get("data", {})).lower()
+                        for event in events
                     )
                     if not marker_found:
-                        print(f"  ⚠ verify failed: test rule written but not readable for {name}")
+                        print(f"  ⚠ verify failed: test correction written but not readable for {name}")
                         had_failure = True
                     else:
                         print(f"  ✓ verify: {name} install confirmed (write+read)")

Gradata/tests/test_quickstart_smoke.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from scripts.smoke_quickstart import smoke
+
+
+def test_offline_quickstart_smoke(tmp_path: Path) -> None:
+    result = smoke(tmp_path)
+    commands = cast("list[str]", result["commands"])
+
+    assert result["database_created"] is True
+    assert result["sessions_trained"] is not None
+    assert any("gradata.cli init" in cmd for cmd in commands)
+    assert any("gradata.cli --brain-dir" in cmd and " correct " in cmd for cmd in commands)