commit 23e96a601e150ab79c6329246a0523d972a625e6
parent f3ddb5aec67c39c9f74b9364a432373d0805db0d
Author: James Eversole <james@eversole.co>
Date: Sat, 24 Oct 2026 18:58:50 -0500
Docs updates
Diffstat:
3 files changed, 2 insertions(+), 125 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+AGENTS.md
*.swp
*.txt
*~
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,123 +0,0 @@
-# AGENTS.md - tricu Project Guide
-
-> For AI agents and contributors working in this repository.
-
-## North star
-
-Always aim to make writing practical programs in tricu better. Judge
-self-hosting, contracts, typed fragments, and tree-calculus-specific ideas by
-what they enable people to write, run, debug, and maintain—not by architectural
-milestones alone. Test ideas on real programs, measure their costs, and state
-safety and performance limits honestly. Preserve tricu's unique intensional
-strengths rather than assuming conventional language features are the answer.
-
-## Research status
-
-There is no legacy code, stable API, or human consumer. Replace flawed
-abstractions rather than preserving them for compatibility. Historical behavior
-is evidence, not automatically the specification: classify differences as intended
-requirements, bugs, or deliberately retired behavior. State corrections explicitly,
-update callers and independent expectations, and retain negative/security controls.
-Git makes source experiments reversible; retained accepted toolchains provide
-executable rollback. Neither replaces testing. Use YYYY.MM.DD CalVer in tricu.cabal
-
-## Documentation discipline
-
-`docs/` is for durable documentation, never work-in-progress notes. Do not put
-agent progress reports, provisional findings, in-flight plans, merge/generation
-reminders, handoff notes, or scratch investigations there—even inside an existing
-guide. Keep those in conversation, commit messages, or external scratch artifacts.
-Describe behavior affirmatively in documentation and comments. Use contrasts
-with excluded behavior only when a positive description cannot accurately convey
-the distinction.
-
-Document supported usage, semantics, implementation contracts, and reproducible
-validation procedures; keep implementation details beside source/tests. Do not
-present unvalidated changes as shipped behavior.
-
-## Build & Test
-
-For tricu compiler build/run commands and focused checks, use
-[`docs/build-and-run.md`](docs/build-and-run.md.html). Keep usage in the guides linked
-there, semantics in the language contract, and implementation details beside
-source/tests. Do not add
-parallel status/roadmap/runbook documents for each implementation slice.
-
-```bash
-# Tests
-nix flake check
-
-# Build tricu executable
-nix build .#
-```
-
-### Compiler checkpoint completion includes cleanup
-
-A verified generation-two compiler is not a finished development checkpoint until
-rolling retention is complete. After pair acceptance and smokes, run the tracked
-`test/bootstrap_retention.py` plan/apply/check workflow in
-[compiler rebuilding](docs/compiler-rebuilding.md.html#rolling-development-retention).
-Keep explicitly selected current and rollback toolchains, their frozen inputs,
-current support preparation, and registered Nix runtime roots. Prune superseded
-scratch objects in the same checkpoint; do not defer this to a future agent.
-The completion check must pass before declaring the checkpoint finished or
-starting the next feature batch. If cleanup is blocked, report the blocker and
-outstanding bytes as an incomplete checkpoint. Recovery archives are never routine
-scratch-cleanup targets. Do not implement retention tooling in ignored scratch.
-
-### Never call `cabal` directly
-
-> **Rule of thumb:** if it builds, links, or tests, it goes through `nix`.
-
-## Project Overview
-
-**tricu** (pronounced "tree-shoe") is a programming-language experiment written primarily in Haskell.
-
-Runtime trees and reduction are in `src/Runtime/Tree.hs`; `src/Runtime.hs` is the
-source-free host API. Source compilation belongs to the portable tricu compiler;
-the historical Haskell frontend has been removed.
-
-### File extensions
-
-- `.hs` - Haskell source
-- `.tri` - tricu language source (used in `lib/`, `test/`, `demos/`)
-- `.arboricx` - Portable executable bundle
-- `.dag` - Serialized kernel DAG
-
-### Haskell tests
-
-Tests live in `test/Spec.hs` and use **Tasty** + **HUnit**.
-
-```bash
-nix flake check
-```
-
-## tricu Language Quick Reference
-
-Before authoring or rewriting `.tri`, read [the language-feature inventory](docs/language-features.md.html).
-Check available syntax and library protocols before proposing new machinery or
-claiming a language gap; verify uncertain behavior with the selected stable compiler.
-
-In public examples, prefer indented continuation and unwrapped `let`, `case`, and
-`do` blocks over layout-only parentheses. Use `<|` or `|>` when they make nested
-calls clearer. Keep parentheses where syntax requires them or grouping is the
-clearest explanation; do not contort code just to eliminate them. Both pipe
-chains associate left-to-right, so repeated `<|` is not nested application.
-
-```
-t → Leaf (the base term)
-t t → Stem Leaf
-t t t → Fork Leaf Leaf
-
-x = t → Define term x = Leaf
-id = (a : a) → Lambda identity (eliminates to tree calculus)
-head (map f xs) → From lib/base.tri
-
-!import module as NS → Import workspace module under namespace
-
--- line comment
-```
-
-## Agent Coordination
-
-You are only permitted to use `intercom` or agent orchestration tools available to you with *explicit user approval*.
diff --git a/README.md b/README.md
@@ -56,8 +56,7 @@ The language, formats, and tools are experimental.
- [Testing](docs/validation.md.html) and [compiler rebuilding](docs/compiler-rebuilding.md.html):
contributor checks, publication, and recovery.
-Other hosts under `ext/` are experimental; use the Haskell host for native development
-and validation.
+Other hosts under `ext/` are experimental; use the Haskell host for native development and validation.
## Acknowledgements
