@fraczak/k 6.8.0 → 6.9.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.9.0] — 2026-10-01 — Reusable Codecs, Dynamic Pattern Derivation & Unified SDK
+
+### Codecs & Type System
+
+- **Dynamic Pattern Derivation**: All codecs derive their closed pattern graphs through `k`'s type system from filter and type expressions via `patternFromFilter`. Handwritten property-list JSON arrays have been completely eliminated from codecs.
+- **Unified Codec SDK**: Added `codecs/runtime/codec-sdk.mjs` exporting a standard CLI harness (`runCodecCLI`), `Value` API, wire codecs, and `patternFromFilter`.
+- **Recipe-Based REPL Codecs**: Refactored the REPL to use explicit recipe-driven input syntax (`:input <codec.mjs> [text]`) and multi-codec output formatting. Removed universal catch-all fallback and ungrounded types.
+- **Self-Contained Web REPL VFS**: The browser REPL compiler (`scripts/build-repl-html.mjs`) bundles verified codecs into zero-import ES modules for the virtual file system, delegating `patternFromFilter` dynamically to the browser's bundled `k` engine.
+- **Dead Code Clean-Up**: Removed dead files (`ieee-pattern.mjs`, `test-codec.mjs`, `typeFromValue.mjs`, `example-pipeline.mjs`).
+
 ---
 
 ## [6.5.0] — 2026-09-22 — Tail-loop arena compaction & OOM diagnostics

package/DOCS/CODECS.md

@@ -1,113 +1,86 @@
 # Writing Codecs
 
-A codec is a small ES module that translates between some external text format
-and k `Value` objects. The same module may serve two entry points:
+A codec is an ES module that translates between an external domain format and enveloped **k** `Value` objects `(P, v)`. The same module serves two entry points:
 
-- a command-line codec such as `k-int --parse` or `k-int --print`,
-- a REPL codec loaded with `:codec load file`.
+- a standalone command-line filter supporting `--parse`, `--print`, and `--help`,
+- a REPL module loaded with `:codec load <file.mjs>`.
 
 The command-line entry point reads or writes the binary pattern+value stream.
-The REPL entry point exports `name`, type metadata, `parse`, and `print`
-functions.
+The REPL entry point provides interactive parsing (`:input <codec.mjs>`) and multi-codec output formatting.
 
-## Choose The Shape
+## Architecture & Mental Model
 
-Use a type-specific codec when the external format belongs to one k type. The
-module exports either `codes` or `patterns`.
+A codec maps between external text and enveloped *k* values:
 
-```js
-export const name = "unit";
-export const patterns = [[
-  ["closed-product", []]
-]];
-```
+- `parse(text)` translates external text to an enveloped *k* value (a `Value` with an associated closed pattern envelope `(P, v)`).
+- `print(value)` translates an enveloped *k* value into formatted external text, throwing an `Error` if the value is not representable.
+- `doc` (optional string) documents the accepted syntax and semantic representation.
 
-Use a universal codec when the external format can describe many k types. A
-universal codec is available for any type named by `:input`; the REPL validates
-the parsed value against that requested type before accepting it.
+Codecs are identified directly by their file name. They do not export artificial identifiers like `name` or pattern registries like `patterns = [...]`.
 
-```js
-export const name = "json";
-export const universal = true;
-```
+In the REPL:
+- **Input**: The user explicitly chooses which codec to parse with:
+  - Interactive mode: `:input <codec.mjs>` sets the prompt to `<codec.mjs>> `, and the next entered line is parsed with that codec.
+  - One-line mode: `:input <codec.mjs> <text>` immediately parses `<text>` using that codec.
+- **Output**: Any evaluated *k* value is displayed in its standard *k* envelope representation, followed by formatting from **all loaded codecs** that can represent it:
+  ```text
+  > 42 int
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
+  ```
+  Every loaded codec attempts `codec.print(value)`. If it succeeds, the REPL prints `<codec.mjs>: <formatted>`. If it throws, the codec is silently ignored for that value.
 
-Prefer `patterns` for codecs that live in the source tree because the REPL
-recomputes the canonical code hash. Use `codes` only when the codec is tied to a
-known canonical hash:
-
-```js
-export const codes = ["@..."];
-```
+## Module Interface
 
-## Implement The REPL API
-
-A REPL codec exports:
+A codec module exports:
 
 ```js
-export const name = "mycodec";
-export const patterns = [MY_PATTERN]; // or codes = ["@..."], or universal = true
+export const doc = "Description of syntax and usage.";
 
-export function parse(text, context) {
-  // text is the line entered after :input
-  // return a k Value
+export function parse(text) {
+  // parse text into an enveloped k Value (P, v) using withPattern(value, pattern)
 }
 
-export function print(value, context) {
-  // return text shown under normal REPL output
+export function print(value) {
+  // return formatted text
+  // throw Error if value is not representable
 }
 ```
 
-`context` contains:
-
-- `codeHash`: the canonical code hash selected by `:input`,
-- `pattern`: the closed property-list pattern for that type,
-- `state`: the current REPL state.
-
-Most codecs do not need `context`. Universal codecs can use it when the same
-text syntax needs to adapt to the requested type.
-
-`parse` should throw an `Error` for invalid external text. `print` should throw
-when the value is not representable by the external format. For universal
-codecs, REPL output suppresses `print` errors so a generic codec does not add
-noise to every value.
+`parse` should throw an `Error` for invalid external text. `print` should throw when the value is not representable by the external format. REPL output suppresses `print` errors so loaded codecs only output when they recognize the value.
 
-## Build Values
+## The Codec SDK & Runner
 
-Use the structural `Value` API:
+To eliminate CLI stream boilerplate, codecs import from `./runtime/codec-sdk.mjs` and invoke `runCodecCLI`:
 
 ```js
-import { Value, isProduct, isVariant } from "../Value.mjs";
-
-const unit = Value.product({});
-const yes = Value.variant("true", unit);
-const point = Value.product({
-  x: Value.variant("+", unit),
-  y: Value.variant("-", unit)
-});
+import { Value, isVariant, withPattern, runCodecCLI } from "./runtime/codec-sdk.mjs";
 ```
 
-Products are JavaScript objects whose keys are k field labels. Variants have a
-string tag and a payload value.
+`runCodecCLI(import.meta.url, { parse, print, doc })` automatically handles:
+1. Entrypoint detection (no-op when loaded as a module or in browsers).
+2. `-h` and `--help` CLI flag handling.
+3. `--parse` and `--print` stream piping and wire encoding/decoding.
 
-## Minimal Type-Specific Codec
+## Minimal Type-Specific Codec Example
 
-This codec accepts `yes` and `no` for the type `<{} true, {} false>`.
+This codec accepts `yes` and `no` for the type `<{} false, {} true>`. Patterns are derived by `k` from filter expressions via `patternFromFilter`:
 
 ```js
-import { Value, isVariant } from "../Value.mjs";
+#!/usr/bin/env node
+
+import { Value, isVariant, withPattern, patternFromFilter, runCodecCLI } from "./runtime/codec-sdk.mjs";
 
-const BOOL_PATTERN = [
-  ["closed-union", [["false", 1], ["true", 1]]],
-  ["closed-product", []]
-];
+const BOOL_PATTERN = patternFromFilter("?< {} false, {} true >");
 
-export const name = "yesno";
-export const patterns = [BOOL_PATTERN];
+export const doc = `
+Boolean codec: accepts 'yes' and 'no'.
+`;
 
 export function parse(text) {
   const word = text.trim();
-  if (word === "yes") return Value.variant("true", Value.product({}));
-  if (word === "no") return Value.variant("false", Value.product({}));
+  if (word === "yes") return withPattern(Value.variant("true", Value.product({})), BOOL_PATTERN);
+  if (word === "no") return withPattern(Value.variant("false", Value.product({})), BOOL_PATTERN);
   throw new Error("expected yes or no");
 }
 
@@ -117,106 +90,30 @@ export function print(value) {
   if (value.tag === "false") return "no";
   throw new Error("expected true or false");
 }
+
+runCodecCLI(import.meta.url, { parse, print, doc });
 ```
 
-Load it in the REPL:
+### Using in the REPL:
 
 ```text
 > :codec load ./codecs/yesno.mjs
-loaded codec yesno for @...
-> :input <{} true, {} false> yesno
-input @... using yesno: enter value text
-yesno> yes
+loaded codec yesno.mjs
+> :input yesno.mjs yes
 {}|true ?<{} false, {} true>
-yesno: yes
-```
-
-## Add The CLI Boundary
-
-To make the same module usable as an installed command, add a `main` function
-that supports `--parse`, `--print`, and `--help`.
-
-```js
-#!/usr/bin/env node
-
-import { stdin, stdout, argv, exit } from "node:process";
-import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
-import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
-
-function usage(stream = console.error) {
-  stream(`Usage: ${argv[1]} --parse | --print`);
-  stream("  --parse      Read yes/no text, write binary pattern+value stream.");
-  stream("  --print      Read binary pattern+value stream, write yes/no text.");
-  stream("  -h, --help   Show this help.");
-}
-
-function readAll(stream) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    stream.on("data", c => chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-async function main() {
-  const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    usage(console.log);
-    exit(0);
-  }
-  if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    usage();
-    exit(1);
-  }
-
-  const input = await readAll(stdin);
-  if (args[0] === "--parse") {
-    stdout.write(encodeToWire(parse(input.toString("utf8")), BOOL_PATTERN));
-  } else {
-    stdout.write(`${print(decodeWire(input).value)}\n`);
-  }
-}
-
-if (isMainEntrypoint(import.meta.url, argv[1])) {
-  main().catch(error => {
-    console.error(error.message || String(error));
-    exit(1);
-  });
-}
+yesno.mjs: yes
 ```
 
-The command-line interface must write only the binary stream to stdout in
-`--parse` mode. Diagnostics belong on stderr.
-
-Installed codec binaries use the `k-` prefix plus the source basename without
-`.mjs`. For example, `codecs/yesno.mjs` installs as `k-yesno` when added to
-`package.json`.
+### Using as a CLI Pipeline Filter:
 
-## Universal Codecs
-
-Universal codecs omit `codes` and `patterns`:
-
-```js
-export const name = "json";
-export const universal = true;
-
-export function parse(text) {
-  // Convert external text to a Value.
-}
-
-export function print(value) {
-  // Convert a Value to external text.
-}
+```sh
+printf 'yes\n' | ./codecs/yesno.mjs --parse | ./codecs/yesno.mjs --print
+# Output: yes
 ```
 
-The built-in [`../codecs/json.mjs`](../codecs/json.mjs) codec is the reference
-example. It derives a pattern for command-line `--parse`, but in the REPL the
-requested `:input` type supplies the target type.
-
-## Test A Codec
+## Testing a Codec
 
-For CLI codecs, test both directions:
+For CLI codecs, test both directions in a pipeline:
 
 ```sh
 printf 'yes\n' | node codecs/yesno.mjs --parse | node codecs/yesno.mjs --print
@@ -227,17 +124,13 @@ For REPL codecs, add a focused case to [`../tests/test-repl.mjs`](../tests/test-
 ```js
 const state = createState();
 let output = await evaluateInput(":codec load ./codecs/yesno.mjs", state);
-assert.match(output[0], /^loaded codec yesno for @/);
-output = await evaluateInput(":input <{} true, {} false> yesno", state);
-assert.match(output[0], /^input @[^ ]+ using yesno: enter value text$/);
+assert.match(output[0], /^loaded codec yesno\.mjs/);
+output = await evaluateInput(":input yesno.mjs", state);
+assert.equal(promptForState(state), "yesno.mjs> ");
 output = await evaluateInput("yes", state);
-assert.match(output[0], /yesno: yes/);
-```
-
-Run the targeted test first:
-
-```sh
-node tests/test-repl.mjs
+assert.match(output[0], /yesno\.mjs: yes/);
+output = await evaluateInput(":input yesno.mjs no", state);
+assert.match(output[0], /yesno\.mjs: no/);
 ```
 
 Then run the full suite before committing:
@@ -246,13 +139,19 @@ Then run the full suite before committing:
 npm test
 ```
 
+## Web REPL (VFS) Bundling
+
+When `repl.html` is generated (`npm run build:repl-html`):
+- Codecs (`int.mjs`, `json.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`) are bundled into 100% self-contained ES modules with zero imports.
+- `runCodecCLI` is shimmed as a no-op, and `Value` helpers are directly inlined.
+- In the browser, the VFS serves these self-contained modules directly to native dynamic `import(blobUrl)`. No runtime helper files (`codecs/runtime/*`) need to be included in the VFS or exposed as globals.
+
 ## Checklist
 
-- Export a stable `name`.
-- Export exactly one dispatch shape: `patterns`, `codes`, or `universal = true`.
-- Keep `parse` and `print` deterministic.
-- Return structural `Value` objects from `parse`.
-- Validate shapes in `print` and throw clear errors.
-- Keep command-line `--parse` stdout binary-only.
-- Add `-h` and `--help` for installed commands.
-- Add REPL coverage for `:codec load` and `:input`.
+- Return an enveloped `Value` from `parse` using `withPattern(val, pattern)`.
+- Keep `parse` and `print` deterministic and free of side effects.
+- Validate shapes in `print` and throw clear errors when not representable.
+- Use `runCodecCLI(import.meta.url, { parse, print, doc })` for CLI execution.
+- No artificial `name` or `patterns` exports required.
+- Add `-h` and `--help` support via `runCodecCLI`.
+

package/DOCS/CODEC_ARCHITECTURE.md

@@ -0,0 +1,194 @@
+# Reusable Codec Architecture
+
+## 1. Overview & Objectives
+
+In **k**, a **codec** is a two-way translator between external domain data (e.g. decimal integers, JSON, UTF-8 text, IEEE 754 floats) and **k** enveloped values (a structural `Value` tree paired with a closed pattern graph).
+
+Every codec in the **k** ecosystem is designed to serve three unified objectives from a single module definition:
+
+1. **Document the Codec**: Formally specify the external syntax and its semantics as an enveloped **k** value `(P, v)`.
+2. **REPL Module**: Provide interactive input parsing (`:input <codec.mjs>`) and multi-codec output inspection (`<codec.mjs>: <formatted>`) in both Node.js and browser REPLs.
+3. **Standalone Shell Executable**: Function as a first-class Unix filter (`--parse`, `--print`, `--help`) for composition in command-line pipelines.
+
+```text
+                     +---------------------------------------+
+                     |          External Domain Data         |
+                     |  (JSON, Decimals, UTF-8, IEEE floats) |
+                     +---------------------------------------+
+                                    |         ^
+                       parse(text)  |         |  print(value)
+                                    v         |
+                     +---------------------------------------+
+                     |               k Codec                 |
+                     |        (Syntax & Value Mapper)        |
+                     +---------------------------------------+
+                         |                               ^
+        CLI: --parse     |                               | CLI: --print
+        REPL: :input     v                               | REPL: output
+                     +---------------------------------------+
+                     |           Enveloped k Value           |
+                     |     (pattern graph P, value tree v)   |
+                     |        Binary Wire Stream (P, v)      |
+                     +---------------------------------------+
+```
+
+---
+
+## 2. Objective 1: Documentation & Specification
+
+Every codec defines what external text it accepts and how that text maps to an enveloped **k** value.
+
+### 2.1 External Syntax
+The syntax specification defines the valid textual forms accepted by the codec:
+- **Grammar & Rules**: Defines the accepted language. While regular expressions offer simple examples, the syntax can be an arbitrary formal language (context-free, recursive, JSON RFC 8259, etc.).
+- **Normalization**: Rules for whitespace, casing, or escaping.
+- **Rejection Criteria**: Explicit errors when invalid input is encountered.
+
+### 2.2 Semantics as an Enveloped k Value
+Parsing external text produces an **enveloped value** `(P, v)`:
+- **Pattern Graph ($P$)**: A closed pattern graph specifying the algebraic structure.
+- **Value Tree ($v$)**: A concrete tree matching $P$, constructed from products (`{...}`) and variants (`<...>`).
+
+A codec does not produce an ungrounded type; it performs a concrete transformation from text to an enveloped value `(P, v)`.
+
+### 2.3 Pattern Derivation via k Type System (`patternFromFilter`)
+Pattern graphs ($P$) must never be handwritten as raw property-list JSON arrays (e.g. `[["closed-union", ...]]`). Instead, codecs derive pattern graphs directly through the **k** type system from filter or type expressions using `patternFromFilter`:
+
+```js
+import { patternFromFilter } from "./runtime/codec-sdk.mjs";
+
+// Derived from k filter expression
+const INT_PATTERN = patternFromFilter('?< <bits 0, bits 1, {} _>=bits "+", bits "-">');
+```
+
+This guarantees:
+1. All patterns are verified, normalized, and canonicalized by **k**'s type derivation and graph unification engine.
+2. Codecs remain concise, declarative, and maintainable.
+3. Codecs run identically in Node.js and in the Web REPL (via the browser runtime shim).
+
+### 2.4 Documentation Contract
+A codec is identified solely by the file loaded—there is no artificial `name` export or `patterns` list export. A codec may optionally export a `doc` string:
+- Describes accepted syntax, options, and representation.
+- Displayed by `--help` in shell invocations.
+- Displayed by `:help <codec.mjs>` or documentation commands in REPLs.
+
+---
+
+## 3. Objective 2: REPL Module Interface
+
+In the REPL, codecs are loaded dynamically on demand:
+```text
+> :codec load int.mjs
+```
+
+### 3.1 Module Exports
+A codec module exports:
+
+| Export | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `parse` | `(text: string) => EnvelopedValue \| Value` | **Yes** | Parses external text into an enveloped `Value`. Throws on syntax error. |
+| `print` | `(value: Value) => string` | **Yes** | Formats a `Value` into external text. Throws if value is not representable. |
+| `doc` | `string` | Optional | Documentation of syntax and usage for CLI help and REPL inspections. |
+
+### 3.2 REPL Input Protocol
+The user specifies the codec to parse an input payload:
+- **Interactive Mode**:
+  ```text
+  > :input int.mjs
+  int.mjs> 42
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
+  ```
+- **One-Line Mode**:
+  ```text
+  > :input int.mjs 42
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
+  ```
+
+### 3.3 REPL Output Protocol (Multi-Codec Inspection)
+Whenever an evaluation produces a resulting **k** `Value`:
+1. The primary representation is the standard **k** value envelope.
+2. The REPL iterates over loaded codecs and calls `codec.print(value)`.
+3. If `codec.print(value)` succeeds, the REPL displays `<codec>: <formattedString>`.
+4. If `codec.print(value)` throws, the codec is silently ignored for that value.
+
+---
+
+## 4. Objective 3: Standalone Shell Executable Contract
+
+Every codec file is directly executable from the command line:
+```bash
+chmod +x codecs/int.mjs
+```
+
+### 4.1 CLI Invocations
+
+1. **Parse Mode (`--parse`)**:
+   - Reads external text from `stdin`.
+   - Parses it into an enveloped value `(P, v)`.
+   - Writes the binary wire encoding of `(P, v)` to `stdout`.
+   - Diagnostics and errors are written to `stderr`.
+   - Exit code: `0` on success, non-zero on error.
+
+2. **Print Mode (`--print`)**:
+   - Reads binary wire bytes `(P, v)` from `stdin`.
+   - Decodes the wire stream and calls `print(value)`.
+   - Writes formatted text to `stdout`.
+   - Exit code: `0` on success, non-zero if not representable under this codec.
+
+3. **Help Mode (`-h`, `--help`)**:
+   - Outputs CLI usage and the codec's `doc` string to `stdout`.
+
+---
+
+## 5. Implementation: Codec CLI Runner
+
+To avoid duplicating stdin/stdout stream handling and CLI flag parsing across codecs, a helper is provided:
+
+```javascript
+runCodecCLI(import.meta.url, { parse, print, doc });
+```
+
+### Responsibilities of `runCodecCLI`:
+1. **Entrypoint Detection**: Checks if the module is invoked directly from the CLI (e.g. `import.meta.url === pathToFileURL(process.argv[1]).href`). If imported as a module or running in a browser, it is a no-op.
+2. **Flag Parsing**: Handles `--parse`, `--print`, and `-h` / `--help`.
+3. **Stream Piping**:
+   - For `--parse`: reads `stdin` to string, calls `parse(text)`, encodes enveloped value `(P, v)` to binary wire format on `stdout`.
+   - For `--print`: decodes wire format from `stdin` into `(P, v)`, calls `print(value)`, writes formatted text to `stdout`.
+
+---
+
+## 6. Directory Layout
+
+To make `codecs/` intuitive and self-contained:
+
+```text
+codecs/
+├── int.mjs                    # Integer & list codec
+├── json.mjs                   # JSON codec
+├── utf8.mjs                   # UTF-8 string codec
+├── utf16.mjs                  # UTF-16 string codec
+├── ieee.mjs                   # IEEE 754 float codec
+├── unit.mjs                   # Unit {} codec
+├── k-parse.mjs                # Textual k value {...} -> binary wire stream
+├── k-print.mjs                # Binary wire stream -> textual k value
+├── show.mjs                   # Wire stream pass-through inspector
+└── runtime/                   # Shared codec infrastructure
+    ├── codec-sdk.mjs          # runCodecCLI, Value, encodeToWire, decodeWire
+    ├── prefix-codec.mjs       # Low-level bitstream wire serialization
+    ├── codec.mjs              # Abstract pattern graph algorithms
+    └── cli-entry.mjs          # Entrypoint detection
+```
+
+Each codec file directly under `codecs/` is both an executable CLI script and an importable module.
+
+---
+
+## 7. Web REPL & VFS Bundling Architecture
+
+In the browser REPL (`repl.html`):
+- **Self-Contained Modules**: At build time (`scripts/build-repl-html.mjs`), verified codecs in `codecs/` are compiled via `esbuild` into 100% self-contained ES modules with **zero imports**.
+- **No Runtime Files in VFS**: `codecs/runtime/*` is not included in the browser VFS. The VFS only contains verified, self-contained user-facing files (`int.mjs`, `json.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`).
+- **Native Browser Loading**: In `repl-codecs.mjs`, the browser reads the codec source from VFS, wraps it in a Blob, and invokes native `await import(blobUrl)`. No regex manipulation, import stripping, or global environment injection is required.
+

package/DOCS/REPL.md

@@ -43,10 +43,10 @@ complete.
 | `:C name` | Show canonical code definition |
 | `:codes` | List type aliases |
 | `:rels` | List relation aliases |
-| `:codec load name\|file` | Load a built-in codec (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file |
+| `:codec load file` | Load a codec from an ES module file (e.g. `:codec load codecs/int.mjs`) |
 | `:codec unload name` | Unload a registered codec |
 | `:codec list` | List loaded REPL codecs (alias: `:codecs`) |
-| `:input [<filter=(...)> [codec]]` | Read next input line using specified codec (opens dialog in browser) |
+| `:input <codec.mjs> [text]` | Read next input line or parse inline text using specified codec |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
 | `:klib file` | Export the active relation closure as a `.klib` library |
 | `:ko file expr` | Export a `.ko` executable with `expr` as main |
@@ -136,9 +136,8 @@ Tab completion covers:
 
 Type aliases also complete in `$name` position inside raw k input.
 
-For codec commands, completion covers `:codec load`, `:codec list`, file paths
-after `:codec load`, type names or codec names after `:input`, and loaded codec names
-after the input pattern or type.
+For codec commands, completion covers `:codec load`, `:codec unload`, `:codec list`,
+file paths after `:codec load`, and codec names after `:input`.
 
 ## Loading
 
@@ -156,55 +155,58 @@ unless `--no-alias` is used.
 
 ## Codecs
 
-REPL codecs are usually keyed by canonical code hashes. Patterns are not used
-for codec dispatch. A codec may also export `universal = true` to make it
-available for any type selected by `:input`; the parsed value is still validated
-against the requested type before it enters the session.
+A codec is a recipe for translating between external text and enveloped *k* values:
+- `parse(text)`: parses an external string into an enveloped *k* value.
+- `print(value)`: serializes an enveloped *k* value to external string, throwing an `Error` if the value is not representable.
 
-For a complete guide to writing a new codec module, see
-[`CODECS.md`](./CODECS.md).
+Codecs can define a family of target patterns (e.g. `int` parses/prints single integers as well as lists like `[0,1,2]`).
 
-### `:codec load name|file`
+For printing in the REPL, every value is printed with the standard *k* envelope representation, followed by lines for all loaded codecs that can format it:
+```text
+> 42 int
+{}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+int: 42
+```
 
-Loads either a built-in codec by name (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file. Loading a built-in codec automatically loads its corresponding `.k` definition file if not already present:
-- `int` auto-loads `Examples/arithmetics.k`
-- `ieee` auto-loads `Examples/ieee.k`
-- `utf8`, `json`, `unit` auto-load `Examples/core.k`
+For a complete guide to writing a new codec module, see
+[`CODECS.md`](./CODECS.md).
 
-Loading a codec also creates code aliases matching the codec name (e.g. `$ int = @...`, `$ float64 = @...`, `$ utf8 = @...`).
+### `:codec load file`
 
-An external codec module exports:
+Loads a codec module from an ES module file (e.g. `:codec load codecs/int.mjs`). Codecs are identified by their file name, and export `parse(text)` and `print(value)` functions.
 
-```js
-export const name = "utf8";
-export const codes = ["@..."];
-export function parse(text) { /* text -> Value */ }
-export function print(value) { /* Value -> text */ }
-```
+### `:codec unload name`
 
-A codec may export `patterns` instead of `codes`; each pattern must be a closed
-property-list pattern that can be canonicalized to a code hash, and that hash is
-recalculated by the REPL. A universal codec exports `universal = true` instead
-of `codes` or `patterns`.
+Unloads a previously loaded codec by name (e.g. `:codec unload int.mjs`).
 
+### `:codec list` (or `:codecs`)
 
-### `:codec unload name`
+Lists all currently loaded codecs and their source files.
 
-Unloads a previously registered codec by name.
+### `:input <codec.mjs> [text]`
 
-### `:input [<filter=(...)> [codec]]`
+Parses external input using the specified codec file.
 
-Resolves a pattern expression (e.g. `? {string a, float64 n}`, `? (...)`, `? <{} true, {} false>`), a type alias, or a canonical code hash, selects the registered codec, and consumes the next line verbatim as codec input.
+- **Interactive mode**: `:input <codec.mjs>` switches the REPL prompt to `<codec.mjs>> `, and the next input line is parsed using that codec:
+  ```text
+  > :input json.mjs
+  json.mjs> {"hello": "world"}
+  {...} ?<{...}>
+  json.mjs: {"hello":"world"}
+  ```
 
-If only a universal codec is specified (e.g. `:input json`), no pre-declared type or pattern is required; input is parsed directly and derives its pattern from the input payload.
+- **One-line mode**: `:input <codec.mjs> <text>` immediately parses `<text>`:
+  ```text
+  > :input int.mjs 42
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
 
-When a pattern expression or type is provided, the parsed value is validated and constrained against that pattern before becoming the current value:
+  > :input int.mjs [0,1,2]
+  {...} ?<{...}>
+  int.mjs: [0,1,2]
+  ```
 
-```text
-> :input ? {string a, float64 n} json
-input ? {string a, float64 n} using json: enter value text
-json> {"a": "Woj", "n": 123}
-```
+Entering `:input` with no arguments displays usage and a list of loaded codecs.
 
 ## Timing and Profiling