docs: add Show HN first-value demo

README.md

@@ -6,7 +6,7 @@
 
 **CoreTex** is a fully local, headless AI operating system inspired by human neuroanatomy and the Unix Philosophy. It operates directly in a sandbox, supercharges your Obsidian vault, orchestrates multi-agent swarms, and executes code within strict Deno / WebAssembly sandboxes. Docker and Firecracker support soon.
 
-*(📸 PLACE YOUR SPLIT-SCREEN TERMINAL GIF HERE SHOWING A 0-TOKEN TASK EXECUTION)*
+![CoreTex ctx-only local workflow demo](docs/assets/coretex-ctx-demo.gif)
 
 ---
 
@@ -33,6 +33,19 @@ ctx task "Audit ./my_project for concurrency race conditions and output to audit
 cat error.log | grep "Timeout" | ctx task "Explain this failure cascade"
 ```
 
+
+### Show HN demo loop
+
+For a deterministic first-value demo that does not require an LLM key, run:
+
+```bash
+python3 scripts/show_hn_demo.py
+cat Professional/show-hn-demo-checklist.md
+```
+
+For the full CoreTex loop with your provider configured, see
+[`docs/ShowHN-Demo.md`](docs/ShowHN-Demo.md).
+
 ---
 
 ## 🚀 Installation (Zero-Debt & Frictionless)

System/tests/test_show_hn_demo.py

@@ -0,0 +1,25 @@
+def test_show_hn_demo_writes_actionable_checklist(monkeypatch, tmp_path):
+    import scripts.show_hn_demo as demo
+
+    fixture = tmp_path / "examples" / "show-hn-mini-project"
+    fixture.mkdir(parents=True)
+    (fixture / "README.md").write_text(
+        "The quickstart should be copy/pasteable from a fresh clone.",
+        encoding="utf-8",
+    )
+    (fixture / "error.log").write_text(
+        "WARN deno not found in PATH\nERROR Permission denied: ./ctx\n",
+        encoding="utf-8",
+    )
+    out = tmp_path / "Professional" / "show-hn-demo-checklist.md"
+
+    monkeypatch.setattr(demo, "ROOT", tmp_path)
+    monkeypatch.setattr(demo, "FIXTURE", fixture)
+    monkeypatch.setattr(demo, "OUT", out)
+
+    assert demo.main() == 0
+    text = out.read_text(encoding="utf-8")
+    assert "executable" in text
+    assert "Deno" in text
+    assert "copy/pasteable" in text
+    assert "secrets" in text

docs/ShowHN-Demo.md

@@ -0,0 +1,43 @@
+# Show HN demo: first useful CoreTex loop
+
+This is the launch-safe demo path for reviewers who want to understand CoreTex
+without handing it a private repo first.
+
+## Goal
+Prove the basic loop in under a minute:
+
+1. inspect local text,
+2. bind it into CoreTex memory,
+3. run one small launch-audit task,
+4. produce a concrete artifact.
+
+## Commands
+
+```bash
+./setup.sh --check || true
+./ctx status
+./ctx absorb examples/show-hn-mini-project --domain Professional --tags show-hn,demo,launch
+./ctx task "Using examples/show-hn-mini-project, write a launch-readiness checklist to Professional/show-hn-demo-checklist.md. Focus on setup clarity, first-run errors, and safe public launch hygiene."
+```
+
+If you do not have an LLM provider configured yet, run the deterministic local
+smoke instead:
+
+```bash
+python scripts/show_hn_demo.py
+cat Professional/show-hn-demo-checklist.md
+```
+
+## Expected artifact
+
+`Professional/show-hn-demo-checklist.md` should contain actionable launch checks
+such as:
+
+- copy/paste quickstart verification,
+- non-mutating help/check commands,
+- missing dependency diagnostics,
+- no secret leakage in generated notes.
+
+## Why this matters
+Passing tests proves the engine is stable. This loop proves the product shape:
+CoreTex turns local workspace context into a useful operational artifact.

examples/show-hn-mini-project/README.md

@@ -0,0 +1,14 @@
+# Show HN Mini Project
+
+This tiny fixture exists so first-time CoreTex users can run a safe, local demo
+without pointing the tool at their own private workspace.
+
+## Scenario
+A small CLI project is about to be posted publicly. The launch owner wants a
+fast reliability pass before sharing it.
+
+## Known risks to notice
+- The quickstart should be copy/pasteable from a fresh clone.
+- Help and status commands should be quiet and non-mutating.
+- Setup diagnostics should explain missing dependencies before doing work.
+- Generated launch notes should avoid secrets and machine-specific paths.

examples/show-hn-mini-project/error.log

@@ -0,0 +1,4 @@
+2026-05-26T22:10:01Z INFO setup started
+2026-05-26T22:10:02Z WARN deno not found in PATH
+2026-05-26T22:10:03Z ERROR quickstart command failed: Permission denied: ./ctx
+2026-05-26T22:10:04Z INFO setup exited before running tests

scripts/show_hn_demo.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Deterministic Show HN demo artifact generator.
+
+This does not call an LLM. It gives reviewers a reliable fallback that exercises
+CoreTex's local-file value proposition and produces the same artifact path used
+by the README-backed demo.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+FIXTURE = ROOT / "examples" / "show-hn-mini-project"
+OUT = ROOT / "Professional" / "show-hn-demo-checklist.md"
+
+
+def main() -> int:
+    readme = (FIXTURE / "README.md").read_text(encoding="utf-8")
+    log = (FIXTURE / "error.log").read_text(encoding="utf-8")
+    findings: list[str] = []
+    if "Permission denied" in log:
+        findings.append("Verify launch scripts are executable in a fresh clone.")
+    if "deno not found" in log.lower():
+        findings.append(
+            "Run setup diagnostics before sandbox-backed tasks and explain missing Deno clearly."
+        )
+    if "copy/pasteable" in readme:
+        findings.append(
+            "Keep the README quickstart copy/pasteable and non-mutating until setup is explicit."
+        )
+    findings.append(
+        "Confirm generated launch notes avoid secrets and machine-specific absolute paths."
+    )
+
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    OUT.write_text(
+        "# CoreTex Show HN demo checklist\n\n"
+        "Generated from `examples/show-hn-mini-project`.\n\n"
+        + "\n".join(f"- {item}" for item in findings)
+        + "\n",
+        encoding="utf-8",
+    )
+    print(f"wrote {OUT.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())