= Seven Tentacles
:toc: left
:toclevels: 3
:icons: font
:source-highlighter: rouge

*Teaching Compiler Architecture to Ages 8-18 Through Progressive Reveal & Playful Mascots*

image::assets/mascots/octopus.svg[Seven Tentacles Logo,200,align="center"]

== The Vision

Seven Tentacles is a *radically innovative 10-year learning framework* that teaches university and graduate-level compiler architecture concepts to children aged 8-18 without them realizing it.

=== The Core Insight

Kids learn by playing games with colorful mascots. At age 8, they meet "Speedy Red" and play racing games. At age 16, they discover that "Speedy Red" has been teaching them about recursive descent parsing, and Red now goes by "Performance Agent Red." They've been learning compilers for 8 years without noticing.

=== The Stack

* **7 cephalopod mascots** (octopus agents) — each teaches one compiler component
* **4 language dialects** (Me, Solo, Duet, Ensemble) — matching their age/maturity
* **Progressive reveal system** — concepts introduced as games, revealed as CS
* **10-year narrative journey** — Cuttle → Squidlet → Duet → Octopus

=== Target Outcome

16-year-olds with *graduate-level understanding* of:

* Parsing & lexical analysis
* Concurrency & async/await
* Type systems & affine types
* AST construction & manipulation
* Audit trails & verification
* Compile-time evaluation
* Language governance & policy enforcement

== The Seven Agents

[cols="1,2,3"]
|===
|Agent |Role |Teaches

|🔴 Red |The Parser |Lexical analysis → Parsing → Syntax trees
|🟠 Orange |The Concurrency Engine |Async/await, scheduling, event loops
|🟡 Yellow |The Type System |Type systems, affine types, memory safety
|🟢 Green |The AST Architect |Abstract syntax trees, code representation
|🔵 Blue |The Auditor |Verification, auditing, tracing, debugging
|🟣 Indigo |The Metaprogrammer |Compile-time evaluation, macros, reflection
|🟤 Violet |The Governance System |Language design, policy enforcement, ethics
|===

== The Cephalopod Journey

[horizontal]
🐚 Cuttle (8-12):: Baby cuttlefish. One tentacle at a time. Visual "Me Language."
🦑 Squidlet (13-14):: Adolescent squid. Names change. CS concepts emerge.
🦑🦑 Duet (15):: Two squid dancing. Explicit agent collaboration.
🐙 Octopus (16+):: Full orchestration. Build complete compilers.

== Quick Start

[source,bash]
----
# Clone the repository
git clone https://gitlab.com/hyperpolymath/seven-tentacles.git
cd seven-tentacles

# Enter development environment
nix develop  # or: guix shell -D -f guix.scm

# Build everything
just build

# Run the reveal demo
just demo

# Run tests
just test
----

== Project Structure

[source]
----
seven-tentacles/
├── curriculum/           # All lesson content
│   ├── cuttle/          # Ages 8-12 (140+ lessons)
│   ├── squidlet/        # Ages 13-14 (210+ lessons)
│   ├── duet/            # Age 15 (70+ lessons)
│   └── octopus/         # Ages 16+ (advanced projects)
├── languages/           # Language implementations
│   ├── me-language/     # Visual Blockly-like
│   ├── solo-language/   # Text with affine types
│   ├── duet-language/   # Two-party protocols
│   └── ensemble-language/ # Full orchestration
├── agents/              # ReScript agent definitions
├── tools/               # Reveal system, lesson player
├── assets/              # Mascots, sprites, sounds
├── docs/                # Pedagogy, teacher guides
├── tests/               # Curriculum tests
└── examples/            # Playable demos
----

== Documentation

* link:VISION.adoc[VISION.adoc] — Complete pedagogical framework
* link:docs/PEDAGOGY.adoc[PEDAGOGY.adoc] — Learning science research
* link:docs/AGENT_INTERVIEWS.adoc[AGENT_INTERVIEWS.adoc] — Agent personalities
* link:docs/TEACHER_GUIDE.adoc[TEACHER_GUIDE.adoc] — Classroom usage

== Contributing

We welcome contributions! Please see our link:CONTRIBUTING.adoc[contribution guidelines].

=== Priority Areas

1. **Curriculum content** — Writing lessons for all 7 agents
2. **Language implementations** — Me, Solo, Duet, Ensemble
3. **Mascot art** — SVG illustrations for all agents
4. **Accessibility** — WCAG 2.1 AA compliance
5. **Translations** — Making it global

== License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

== Acknowledgments

Designed by Jonathan D.A. Jewell with contributions from the global CS education community.

---

_"The Seven Tentacles framework combines pedagogical innovation, narrative design, and formal CS concepts into a unified system. This is not just another educational game — it's a 10-year learning journey that secretly teaches graduate-level concepts."_
