1 files changed, 76 insertions, 0 deletions

diff --git a/docs/adr/0002-keyword-redirection-and-post-filters.md b/docs/adr/0002-keyword-redirection-and-post-filters.md
new file mode 100644
index 0000000..1584077
--- /dev/null
+++ b/docs/adr/0002-keyword-redirection-and-post-filters.md
@@ -0,0 +1,76 @@
+# ADR 0002 — Keyword Redirection and Post-Filter Flags Instead of Pipes
+
+## Status
+
+Accepted.
+
+## Context
+
+The shell (a freestanding, no_std kernel component) needs the data-flow
+features every shell has: redirecting command output to files, feeding
+input from files or typed blocks, and trimming output to `head`/`tail`/
+`grep`/pager views.  The obvious model — Unix pipes plus `> < << >>`
+operators — was considered and rejected.  The project is explicitly
+not POSIX-compatible, is TempleOS-inspired, and values minimal machinery
+and natural-language-flavoured input over familiarity.  The old shell
+had only an ad-hoc `>`/`>>` parse baked into `cmd_echo`, no head/tail/
+grep at all, and ^D at the prompt powered the machine off.
+
+## Decision
+
+One canonical command-line grammar, applied uniformly to every command:
+
+```
+cmd args [USE src] [TIL marker] [filters…] [output kw dst]
+```
+
+- **Redirection uses reserved uppercase keywords**, never symbols:
+  `WRITING`/`WRITE` overwrite, `TO` appends, `USE`/`USING` names the
+  input source, `TIL`/`UNTIL` truncates the input at an exact full-line
+  marker (marker and everything after it is discarded).  At most one
+  input keyword (USE and TIL may pair, USE first) and one output
+  keyword; input keywords precede the filters, the output keyword
+  comes last.
+- **Filters are trailing flags** applied left to right as stages over a
+  line stream: `-h N` (emit first N lines, then kill the upstream
+  command), `-t N` (hold back a rolling window of the last N lines;
+  emit only when the stream ends — EOF or ^C, which flushes),
+  `-g PAT` (smart-case literal substring match: case-insensitive unless
+  PAT contains an uppercase letter), `-p` (pause at each screenful,
+  `more`-style, only when output exceeds one screenful).  Every flag
+  may repeat; each instance is another stage.  After `-g`, the next
+  token is the pattern verbatim.
+- **There are no pipes.**  The four built-in filters cover the cases
+  pipes are usually built for; arbitrary command composition is
+  deliberately out of scope.
+- **`> >> < <<` are removed** — `>` is now ordinary text.  The shell
+  prints to both GOP and serial; a file sink replaces terminal output
+  entirely.
+- **^D is EOF everywhere and no longer powers off** (^C keeps its
+  line-cancel / stream-abort role; `poweroff`/`exit` are the only
+  shutdown verbs).
+- **Quoting (`"..."` groups and literalizes, `\x` escapes one char)**
+  is the escape hatch: quoted/escaped text is never an operator, which
+  makes keywords expressible as data and enables spaces in filenames.
+
+## Consequences
+
+- **Positive:** One grammar, one parser — the per-command redirection
+  hacks (`cmd_echo`'s `>` scan) disappear.  Filters compose uniformly
+  with any command and with each other, including intermediate views
+  (`-h N -p -g pat -p` shows each stage's result).  No pipe machinery,
+  no process/stream abstraction to build.  Lowercase text can never
+  collide with operators, so ordinary words stay ordinary.
+- **Positive:** `tail` on an infinite stream (`cat /dev/mem -g 100
+  -t 10`) is expressible without a pipe; ^C flushes the held-back
+  window instead of losing it.
+- **Negative:** Breaks existing muscle memory and tooling: POSIX users
+  must learn the keywords; `scripts/test-disk.sh` and the `help` text
+  must be rewritten from `echo >` to the keyword syntax.
+- **Negative:** Keywords are reserved, so printing text like `WRITING`
+  requires quoting; unknown commands cannot be filtered with flags
+  beyond the four built-ins; there is no way to compose arbitrary
+  commands (accepted — the shell has no external commands today).
+- **Negative:** `-t` on a stream that never ends shows nothing until
+  the user ^C's — an intentional trade-off for simplicity (no pager
+  machinery, no infinite buffering beyond the window).