QUICKSTART-USER.adoc

tangle — Quick Start for Users

Table of Contents

• What is tangle?
• Prerequisites
• Install
  • Option 1: Standard Install (recommended)
  • Option 2: Container (via Stapeln)
  • Option 3: Portable (no system changes)
• First Run
• Self-Diagnostic
• Get Help
• Uninstall
• Next Steps

What is tangle?

Tangle — See README.adoc for details.

Prerequisites

Before you begin, ensure you have:

• just — task runner (install guide)

• Platform-specific requirements listed below

Platform	Additional Requirements
Linux	See README.adoc
macOS	See README.adoc
Windows	See README.adoc

Install

Option 1: Standard Install (recommended)

# Clone and set up
git clone https://github.com/hyperpolymath/tangle.git
cd tangle

# Build the compiler (`just setup` never existed)
sudo apt-get install -y ocaml ocaml-dune menhir
cd compiler && dune build

There is no setup script — the build IS the setup. dune build produces a single self-contained native executable at compiler/_build/default/bin/main.exe, which needs nothing at runtime beyond libc. There is no configuration step and no install location to choose.

Option 2: Container (via Stapeln)

# `just stapeln-run` does not exist. Run the built binary:
./compiler/_build/default/bin/main.exe --repl

Option 3: Portable (no system changes)

# No `just install` recipe — the build IS the artefact:
cp ./compiler/_build/default/bin/main.exe ./tanglec

First Run

# `just run` does not exist. Invoke the compiler on a file:
./compiler/_build/default/bin/main.exe --eval examples/isotopy.tangle

Expected output — one line per assertion, exit 0 (verified, not assumed):

$ ./compiler/_build/default/bin/main.exe --eval examples/isotopy.tangle
assertion passed
assertion passed
assertion passed
assertion passed
assertion passed
assertion passed
assertion passed
assertion passed
$ echo $?
0

That file is worth reading: it asserts Reidemeister II cancellation and far commutation, and it only passes because ~ decides braid-group equivalence (TG-7, #50). Before that change it failed with Runtime error: Assertion failed.

Self-Diagnostic

If something isn’t working:

just doctor

This checks all dependencies, permissions, paths, and connectivity. If it finds issues, it will suggest fixes.

To attempt automatic repair:

# `just heal` does not exist. The real self-checks are:
just doctor        # diagnostic
just check-all     # build + full suite + corpus gate

Get Help

• CLI: ./compiler/_build/default/bin/main.exe --repl then explore; see README.adoc

• Guided tour: just tour

• Report a problem: just help-me (pre-fills diagnostic context)

• Wiki: https://github.com/hyperpolymath/tangle/wiki

Uninstall

# Nothing is installed system-wide: delete the clone and any copy you made.
rm -f ./tanglec

You will be asked:

1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure)

2. Whether to include or exclude your data

3. Whether to clear caches and LLM models

Next Steps

• Read the README for full feature overview

• Read the EXPLAINME for architecture and design decisions

• Try just tour for a guided walkthrough