Polish Show HN README demo flow

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,22 @@ 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
+
+The README GIF uses only CoreTex commands:
+
+```bash
+ctx status
+ctx absorb examples/show-hn-mini-project --domain Professional --tags show-hn,demo
+ctx daydream "Review the absorbed demo context and identify the next useful action" --domain Professional
+ctx print-daydream --lines 40
+```
+
+`ctx print-daydream` writes the DMN ledger to stdout, so it composes naturally with Unix tools and pipes.
+
+For a deterministic non-LLM fallback demo, see [`docs/ShowHN-Demo.md`](docs/ShowHN-Demo.md).
+
 ---
 
 ## 🚀 Installation (Zero-Debt & Frictionless)
@@ -48,7 +64,7 @@ chmod +x setup.sh
 
 For a non-interactive runtime choice, use `./setup.sh --local` or `./setup.sh --docker`.
 
-*Note: The script automatically evaluates your localized package manager (`apt`, `dnf`, `yum`, `pacman`, `apk`, or `brew`) to resolve missing system dependencies like `curl`, `unzip`, and `file`.*
+*Note: The script automatically evaluates your localized package manager (`apt`, `dnf`, `yum`, `pacman`, `apk`, or `brew`) to resolve missing system dependencies like `curl`, `unzip`, `file`, and Python prerequisites when possible.*
 
 ### 🔷 Windows (PowerShell)
 To bypass native Windows script execution restrictions safely without modifying your global system security profile, execute the script via this process-isolated command:

System/cli.py

@@ -37,6 +37,7 @@
     list_reflexes,
     map_topology,
     observe,
+    print_daydream,
     reflex,
     sleep,
     status,
@@ -367,6 +368,8 @@ def run_absorb(
 somatic_app.command(name="map-topology")(map_topology)
 somatic_app.command(name="status")(status)
 somatic_app.command(name="list-reflexes")(list_reflexes)
+somatic_app.command(name="print-daydream")(print_daydream)
+app.command(name="print-daydream")(print_daydream)
 somatic_app.command(name="reflex")(reflex)
 somatic_app.command(name="sleep")(sleep)
 somatic_app.command(name="assimilate")(assimilate)

System/cli_somatic.py

@@ -44,6 +44,28 @@ def status():
     console.print("\n")
 
 
+def print_daydream(
+    path: Path = typer.Option(
+        ROOT_DIR / "Meta" / "DMN" / "daydreams.md",
+        "--path",
+        "-p",
+        help="Daydream ledger path to print.",
+    ),
+    lines: Optional[int] = typer.Option(
+        None, "--lines", "-n", help="Only print the last N lines."
+    ),
+):
+    """Prints the DMN daydream ledger to stdout for Unix pipes."""
+    if not path.exists():
+        console.print(f"[bold yellow]No daydream ledger found at {path}[/bold yellow]")
+        raise typer.Exit(code=1)
+
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if lines is not None:
+        text = "\n".join(text.splitlines()[-lines:])
+    console.print(text)
+
+
 def list_reflexes():
     """Reflex Arc: Lists all consolidated muscle memories (Engrams) in the Cerebellum."""
     from System.tools import list_engrams

System/tests/test_show_hn_cleanup.py

@@ -0,0 +1,25 @@
+from typer.testing import CliRunner
+
+from System.cli import app
+
+
+def test_print_daydream_outputs_tail(tmp_path):
+    ledger = tmp_path / "daydreams.md"
+    ledger.write_text("one\ntwo\nthree\n", encoding="utf-8")
+
+    result = CliRunner().invoke(
+        app, ["print-daydream", "--path", str(ledger), "--lines", "2"]
+    )
+
+    assert result.exit_code == 0
+    assert "two" in result.stdout
+    assert "three" in result.stdout
+    assert "one" not in result.stdout
+
+
+def test_setup_prompts_to_install_missing_python():
+    text = open("setup.sh", encoding="utf-8").read()
+
+    assert "install_python_runtime" in text
+    assert "Install Python prerequisites now?" in text
+    assert "python3-venv" in text

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())

setup.sh

@@ -69,6 +69,61 @@ sys.exit(0 if sys.version_info[:2] >= need else 1)
 PY
 }
 
+python_install_hint() {
+    if command_exists apt-get; then
+        echo "sudo apt-get update && sudo apt-get install -y python3 python3-venv"
+    elif command_exists dnf; then
+        echo "sudo dnf install -y python3"
+    elif command_exists yum; then
+        echo "sudo yum install -y python3"
+    elif command_exists pacman; then
+        echo "sudo pacman -Sy --noconfirm python"
+    elif command_exists apk; then
+        echo "sudo apk add python3 py3-pip"
+    elif command_exists brew; then
+        echo "brew install python@${CORETEX_MIN_PYTHON}"
+    else
+        echo "Install Python ${CORETEX_MIN_PYTHON}+ from https://www.python.org/downloads/"
+    fi
+}
+
+install_python_runtime() {
+    if python_version_available; then
+        return 0
+    fi
+    local hint
+    hint="$(python_install_hint)"
+    echo -e "\033[1;33m[!] Python ${CORETEX_MIN_PYTHON}+ is required for local setup.\033[0m"
+    echo "Suggested install command: $hint"
+    if ! confirm_default_yes "Install Python prerequisites now?"; then
+        echo -e "\033[1;31mAborting. Install Python ${CORETEX_MIN_PYTHON}+ manually, or run ./setup.sh --docker.\033[0m" >&2
+        return 1
+    fi
+    SUDO=""
+    if [ "$(id -u)" -ne 0 ] && command_exists sudo; then SUDO="sudo"; fi
+    if command_exists apt-get; then
+        $SUDO apt-get update -y
+        $SUDO apt-get install -y python3 python3-venv
+    elif command_exists dnf; then
+        $SUDO dnf install -y python3
+    elif command_exists yum; then
+        $SUDO yum install -y python3
+    elif command_exists pacman; then
+        $SUDO pacman -Sy --noconfirm python
+    elif command_exists apk; then
+        $SUDO apk add python3 py3-pip
+    elif command_exists brew; then
+        brew install "python@${CORETEX_MIN_PYTHON}"
+    else
+        echo -e "\033[1;31mERROR: unsupported package manager. $hint\033[0m" >&2
+        return 1
+    fi
+    if ! python_version_available; then
+        echo -e "\033[1;31mERROR: Python ${CORETEX_MIN_PYTHON}+ still unavailable after install. Try opening a new terminal or run ./setup.sh --docker.\033[0m" >&2
+        return 1
+    fi
+}
+
 print_next_steps() {
     cat <<'EOF'
 
@@ -320,10 +375,7 @@ fi
 
 echo -e "\n[*] \033[1;36mInitializing Pure Local Environment...\033[0m"
 
-if ! python_version_available; then
-    echo -e "\033[1;31mERROR: Python ${CORETEX_MIN_PYTHON}+ is required for local setup. Install Python ${CORETEX_MIN_PYTHON}+ or run ./setup.sh --docker.\033[0m" >&2
-    exit 1
-fi
+install_python_runtime
 
 install_uv_runtime
 install_deno_runtime