feat: package CARL encoders and unify the 0.22 product identity

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "carl",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Coherence-Aware Reinforcement Learning and bidirectional local agent workflows.",
   "author": {
     "name": "Tej Desai"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "carl",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Coherence-Aware Reinforcement Learning and bidirectional local agent workflows.",
   "author": {
     "name": "Tej Desai"

.github/workflows/verify.yml

@@ -25,10 +25,11 @@ jobs:
           version: "0.12.23"
       - run: uv lock --check
       - run: uv sync --locked --extra dev --extra training --extra mcp --extra cli --extra observe --extra hf --extra constitutional --extra secrets
-      - run: uv run --locked --no-sync pytest tests/ packages/carl-core/tests/ -q --tb=short
+      - run: uv run --locked --no-sync pytest tests/ packages/carl-core/tests/ packages/carl-encoders/tests/ -q --tb=short
       - run: uv run --locked --no-sync python scripts/check_moat_boundary.py
       - run: uv run --locked --no-sync python -m build
       - run: uv run --locked --no-sync python -m build packages/carl-core
+      - run: uv run --locked --no-sync python -m build packages/carl-encoders
   codec:
     runs-on: ubuntu-latest
     steps:

DESIGN.md

@@ -0,0 +1,44 @@
+# CARL design
+
+## Purpose
+Improve models. Keep the evidence. CARL means Coherence-Aware Reinforcement Learning.
+Intuition Labs LLC is the existing copyright holder. terminals is lowercase.
+
+## Audience
+Developers need reproducible packages, operators need bounded experiments, and
+people learning the system need explicit examples with visible consequences.
+
+## Visual language
+Paper #FAF6EE, graphite #45424B, attention #9D591C, confirmed #2E6351,
+derived #635186, muted #6B6570. Tin/Tinny share the paper foundation; their
+character artwork remains with its owners. CARL uses independently authored
+diagrams. Do not copy private or differently licensed components or artwork.
+System sans-serif text and monospace references avoid redistributing fonts.
+Dark #06090A is reserved for representation detail and sourced measurements.
+The terminal adapts these roles to light ink #E9F0F0, labels #B9CCCC, attention
+#F2B35E, confirmation #9ECFD0 and muted #8AA3A3 for readable dark terminals.
+Saved user palettes remain configurable. Diagram colors do not paint the terminal background.
+
+## Meaning and motion
+Amber denotes a pending choice, teal explicit confirmation, violet a derived
+artifact. Every color has a written label. Arrows show real order or lineage.
+Illustrated workflows are labeled as examples, never as measured results.
+GIFs have matching static SVG and text equivalents. The gallery displays static
+SVGs; animations are separate, explicit downloads. No autoplay conveys model thinking.
+
+## Brand family
+CARL is the public product; carl-encoders is its Python package; CARL Encoder
+is the proposed model family. A release candidate is not an accepted model.
+Tin is the parent composition, Tinny its agent, cans its reusable context
+harness. These relationships do not imply shared implementation or licensing.
+
+## Compatibility
+CampConsole, CampTheme, carl camp commands, saved themes and service addresses
+remain compatible. The default banner and CARL voice use precise product
+language. CARLI remains an explicit legacy persona. Existing URLs stay valid.
+
+## Rights and ownership
+New diagram source and generated graphics use this repository's MIT license.
+Software licensing does not license upstream weights, training data, external
+artwork, company marks or third-party fonts. Model artifacts require their own
+notices and provenance. Internal launch procedures stay outside this repo.

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/carl-hero.gif" alt="CARL: from chaos to crystal" width="720"/>
+  <img src="assets/brand/carl-overview.svg" alt="CARL: improve models and keep the evidence" width="720"/>
 </p>
 
 <h1 align="center">CARL</h1>
@@ -9,34 +9,36 @@
 </p>
 
 <p align="center">
-  <a href="https://pypi.org/project/carl-studio/"><img src="https://img.shields.io/pypi/v/carl-studio?color=06b6d4&style=flat-square" alt="PyPI"/></a>
-  <a href="https://pypi.org/project/carl-studio/"><img src="https://img.shields.io/pypi/pyversions/carl-studio?style=flat-square" alt="Python"/></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"/></a>
-  <a href="https://doi.org/10.5281/zenodo.18906944"><img src="https://img.shields.io/badge/paper-Zenodo-blue?style=flat-square" alt="Paper"/></a>
+  <a href="https://pypi.org/project/carl-studio/">Python package</a> · <a href="LICENSE">MIT source</a> · <a href="https://doi.org/10.5281/zenodo.18906944">Paper</a>
 </p>
 
 ---
 
-## Why
+## Improve models. Keep the evidence.
 
-A model becomes an agent when it stops pattern-matching and starts *knowing*. That transition isn't gradual — it's a **phase transition**, like water becoming ice. One moment the model is guessing. The next, it's coherent.
+CARL prepares bounded training experiments, compares candidates against their
+starting models, and keeps task results, policy checks, coherence and cost
+separately visible. Coherence is a measurement; held-out task evaluation
+establishes whether the model improved for your goal.
 
-Standard training can't see this happening. You watch a loss curve and hope.
+The encoder interface adds source-linked retrieval and explicit interpretation
+feedback. A correction can become a local learning example when capture is
+enabled. Capture permission and training permission are separate.
 
-**CARL measures the moment of crystallization** — and rewards it.
+Install the encoder integration with `pip install 'carl-studio[encoders]'`.
+The worker uses its separately bound interpreter and dependency environment.
 
-```
-                         Phi (order parameter)
-                              │
-          guessing            │         knowing
-     ░░░░░░░░░░░░░░░░░░░░░░░░│████████████████████████
-                              │
-                        crystallization
-```
+The `carl-encoders` package contains reusable representation contracts and
+isolated training workers. CARL owns sessions, memory, authorization and
+activation. Model releases carry their own weights, processor bindings,
+license notices and evaluation evidence. GGUF is a derived artifact that
+requires conversion and runtime qualification.
 
-The order parameter **Phi** measures how coherent a model's probability field is at every token. When Phi crystallizes, the model has found its internal anchor — a fixed point it can navigate from to *any* concept space without losing itself.
+[Explore the illustrated workflows](assets/brand/index.html) ·
+[Brand and terminology](DESIGN.md) ·
+[Software and model boundaries](docs/public-private-boundaries.md)
 
-This is alignment you can measure, not just evaluate.
+By **Intuition Labs LLC**, for **terminals**.
 
 ---
 

assets/brand/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CARL · Improve models. Keep the evidence.</title>
+<style>
+:root{color-scheme:light;--paper:#FAF6EE;--ink:#45424B;--attention:#9D591C;--confirmed:#2E6351;--derived:#635186}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:18px/1.6 system-ui,sans-serif}main{max-width:1160px;margin:auto;padding:40px 24px}header{display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}h1{font-size:clamp(32px,5vw,60px);line-height:1.1;max-width:850px}h2{font-size:28px}p{max-width:850px}a{color:var(--derived)}button{font:inherit;background:transparent;border:1px solid var(--ink);border-radius:8px;padding:8px 18px;color:var(--ink);cursor:pointer}button:focus-visible,a:focus-visible{outline:3px solid var(--attention);outline-offset:4px}figure{margin:32px 0 64px}img{width:100%;height:auto;display:block}figcaption{margin-top:12px}.roles{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:24px}.roles article{border-top:2px solid var(--derived);padding-top:12px}footer{border-top:1px solid var(--ink);padding-top:20px}small{font-size:15px}section{scroll-margin-top:20px}
+</style>
+<main><header><strong>CARL</strong><span>Intuition Labs LLC · terminals</span></header>
+<h1>Improve models.<br>Keep the evidence.</h1>
+<p>Coherence-Aware Reinforcement Learning. Prepare a bounded experiment, compare a candidate with its starting model, and keep the evidence behind the decision.</p>
+<nav aria-label="Illustrated workflows"><a href="#learning">Learning</a> · <a href="#feedback">Corrections</a> · <a href="#views">Representations</a> · <a href="#ownership">Ownership</a></nav>
+<section id="learning"><h2>From a goal to a measured candidate</h2><figure><img src="carl-overview.svg" alt="Prepare sources and limits, learn within the budget, compare held-out action and retention, then accept, reject or mark inconclusive." data-story="carl-overview"><figcaption>Illustrated workflow. A training run does not establish improvement by itself.</figcaption><a href="carl-overview.gif" download>Download GIF</a> · <a href="carl-overview.svg" download>Download SVG</a></figure></section>
+<section id="feedback"><h2>Corrections retain their context</h2><figure><img src="interpretation.svg" alt="Propose an interpretation, clarify alternatives that change the action, receive explicit confirmation or correction, and commit the accepted artifact once." data-story="interpretation"><figcaption>Fictional example: “Lighten it” initially suggests pale colors. “I mean fewer bytes” corrects the interpretation to removing unused assets. Bundle size still needs measurement. Silence remains unconfirmed.</figcaption><a href="interpretation.gif" download>Download GIF</a> · <a href="interpretation.svg" download>Download SVG</a></figure></section>
+<section id="views"><h2>One representation, several scoring views</h2><figure><img src="representation.svg" alt="Ordered source inputs produce one raw 768-dimensional carrier. Normalize prefixes at 128, 256, 512 and 768 dimensions for scoring and return source-linked results." data-story="representation"><figcaption>Initial scoring recipes start at 128 dimensions for text and 256 for multimodal inputs. Refine at 512 and 768. These dimensions describe the initial qualified binding. Other encoders expose their own capabilities.</figcaption><a href="representation.gif" download>Download GIF</a> · <a href="representation.svg" download>Download SVG</a></figure></section>
+<section id="ownership"><h2>Licenses follow the thing being released</h2><figure><img src="boundaries.svg" alt="Public MIT packages, separately licensed private runtime, model artifacts with their own notices, and private internal launch procedures have separate owners."><figcaption>A software license does not establish permission to redistribute a model, dataset, font or external artwork.</figcaption></figure></section>
+<section><h2>The same system, explained for your work</h2><div class="roles"><article><h3>Developer</h3><p>Use source-linked representations through <code>carl-encoders</code>. Integrate sessions and prepared runs through CARL.</p></article><article><h3>Operator</h3><p>Bind data, goal, grader and limits. Review held-out results before activating a candidate. Retain a rollback predecessor.</p></article><article><h3>Learning the system</h3><p>CARL helps you test whether a change improves a model for your task. Your correction can become a learning example when capture is enabled.</p></article></div></section>
+<footer><p>Recorded pilot: parameters updated; held-out ranking stayed 1.0 → 1.0. No accepted candidate or qualified GGUF is claimed here.</p><small>Independently authored explanatory diagrams. MIT source and graphics. No third-party font files or Tinny artwork are bundled.</small></footer></main>
+</html>