docs: remove temporary notes and fix onboarding drift

- delete TASKLIST.md and docs/design/handoff.md; the handoff content lives in README.md
- move docs/BOOTSTRAP-OWNERSHIP.md to docs/history/ and index it in docs/history/README.md
- point ONBOARD.md, docs/BORROW.md and the ticked TODO.md item at the new path
- ONBOARD.md section 9 no longer mentions TASKLIST.md
- ONBOARD.md section 3 and 4 markers are now `// ...` (line comments lost their colon)

verified from a clean build: make clean, make (fixpoint 376903 words), the
section 0-7 commands (section 4 after the marker fix), and the rejection suites. make check was
started but did not complete (stopped before it finished).

7 files changed, 8 insertions, 1230 deletions

diff --git a/ONBOARD.md b/ONBOARD.md
index 7b0c045..a0ed367 100644
--- a/ONBOARD.md
+++ b/ONBOARD.md
@@ -70,7 +70,7 @@ explain why `include rt;` is required before `rt.put_n`.
 
 ## 3. ownership, the analyzer's view
 
-read `docs/BORROW.md`, then `docs/BOOTSTRAP-OWNERSHIP.md` (how two missing rules
+read `docs/BORROW.md`, then `docs/history/BOOTSTRAP-OWNERSHIP.md` (how two missing rules
 once stopped the compiler compiling itself). run the rejection suites and read a
 few of the fixtures, each of which starts with the message it expects:
 
@@ -81,7 +81,7 @@ bash tests/runerr.sh build/bin/zy tests/langerrors
 ```
 
 in `src/compiler/compiler.zc`, find the block that starts at
-`//: the rules below are the heart of the analyzer` and read `recast`,
+`// the rules below are the heart of the analyzer` and read `recast`,
 `argcheck`, `assigncheck` and `retcheck`, then `exit_vars` and the `lend_*`
 helpers.
 
@@ -95,7 +95,7 @@ does to them.
 overview. read the overview, then use the section markers to navigate:
 
 ```sh
-grep -n "^//: ----" src/compiler/compiler.zc
+grep -n "^// ----" src/compiler/compiler.zc
 ```
 
 read in this order: interning and symbols, the lexer (`lex1`), expressions
@@ -171,8 +171,8 @@ headers for the llvm section.
 
 ## 9. history and open work
 
-`docs/history/README.md` is the scrapbook of earlier stages, `TODO.md` the
-maintenance checklist, and `TASKLIST.md` the record of past requests. read the
+`docs/history/README.md` is the scrapbook of earlier stages and `TODO.md` the
+maintenance checklist. read the
 open items in `TODO.md` last: by then each one should point at code you have
 seen.
 
diff --git a/TASKLIST.md b/TASKLIST.md
deleted file mode 100644
index 8d081d9..0000000
--- a/TASKLIST.md
+++ /dev/null
@@ -1,1203 +0,0 @@
-# TASKLIST — "Review and polish project code"
-
-Complete inventory of every request made by the user in codex session
-`01a12a7c-8c55-7873-a0ae-da32c723ce8c` (2026-10-11 → 2026-10-14, workspace
-`~/Documents/Playground/tinyvm`).
-
-Each item gives **the request in summary** followed by **the user's exact
-message, verbatim** in a blockquote. Section 14 holds the complete raw
-transcript with nothing removed.
-
----
-
-## Follow-up: found after that session
-
-Not part of the session transcript. These came out of the `src/` and history
-cleanup that followed, and they are now blocking work.
-
-### `make` cannot bootstrap from a clean checkout
-
-**Written up in [`docs/BOOTSTRAP-OWNERSHIP.md`](docs/BOOTSTRAP-OWNERSHIP.md)**,
-linked from `docs/BORROW.md`, with a TODO entry. Reproduce with
-`bash src/tools/bootstrap-check.sh`.
-
-The second bootstrap stage runs the lifetime checker over the compiler's own
-source and reports 8 errors, so `bin/mkgenome` reads the diagnostics as if they
-were an image:
-
-```
-mkgenome: input is not a genome for this map
-```
-
-Two ownership completeness limits are responsible:
-
-1. **No move between two locals.** Every accepted move originates at a call
-   (`m*rt.new(...)`, `m*inc_open(...)`, `chk_resize(...)`). An owned value held
-   in a local can be disposed with `d*`, but cannot be handed to another local,
-   and cannot replace one. The documented `rt.free(buffer); buffer =
-   replacement;` rule only fires when the replacement comes from a call.
-2. **A local cannot be lent to a global.** Redirecting the output stream at a
-   scratch buffer is a borrow, but every spelling is a transfer, so the buffer
-   must live at module scope — which costs reentrancy safety.
-
-Neither limit accepts an unsafe program; both refuse correct ones. So it is a
-completeness gap, not a soundness bug. A verified partial fix (promoting the
-scratch buffer to a module global, the existing `sgb` idiom) removes 5 of the
-8 errors.
-
-Also found along the way: `lookup_raw` compared against `K_VAR`, a constant that
-was never declared, so `make genome` could not run at all before that.
-
----
-
-## 0. Standing instructions (apply to everything)
-
-### Commands must be single-line
-
-> When writing commands for the user, never write them as multi-line (with
-> backslashes)
-
-(from `AGENTS.md` injected into the session)
-
-### Delegate mechanical work to subagents
-
-> if you require busywork that you consider repetitive, easy to complete, but not
-> suitable for a bash run, use a 6-luna subagent to do so.
-
-### Small test intervals, not the full suite
-
-> also, please run tests in small intervals. don't run the full suite repeatedly
-> as it takes a good couple minutes
-
-### Don't stop until done
-
-> don't stop until the todo list is done.
-
-> continue and don't stop
-
-(repeatedly set and re-set as the session goal)
-
-### Keep `TODO.md` current
-
-> write your tasks to a TODO.md file
-
-> make sure to add these to the todo file.
-
-> add these to tasks and todo.md:
-
-> don't forget to tick off tasks that you complete in TODO.md.
-
-> don't forget to update the todo.md.
-
-> re-order the todo file based on the order of tasks that you'll complete.
-
-> did you update todo?
-
-> ummm... if it's updated, why are there still headers... and, why aren't the
-> crossed off tasks all at the start, since they've been implemented already? do
-> you understand how sorting works?
-
-> add these to todo.md
-
-> update todo.md
-
-> also, add a hint for when a function argument is never used in the body. add to
-> todo.md
-
-> also add a --help to the compiler, lsp, etc. put in todo
-
-### Comment and doc style
-
-> the comments and docs shouldnt have uppercase :( follow the writing style of the
-> older comments
-
-> keep the lowercase, just remove the informal ai slop and replace it with
-> professional compiler docs and guidance prose
-
----
-
-## 1. Code review, bugs, and polish
-
-### Read the code first
-
-> read the code and familiarize yourself.
-
-### Find bugs and optimizations
-
-> - find bugs and areas for optimizations.
-
-### Clean up phrasing and dirty references
-
-> - clean up the phrasing, there are leftover dirty references such as "task X"
-> in the documentation and code.
-
-### Consistent comment style
-
-> - make the commenting style consistent, and avoid connecting comments to
-> unrelated variables.
-
-### Polish the learning documents
-
-> - polish the learning documents and ensure they're clear, direct, properly
-> sectioned, and easy to understand.
-
-### Fix the hover-renders-as-plain-text bug
-
-> - make sure this bug is fixed: hovering over something in vscode renders it as
-> plain text, rather than formatted markdown and code. this was claimed to have
-> been solved in the latest changes, but it's not a guarantee, so i need you to
-> look at it again.
-
----
-
-## 2. Memory limits, build, and run
-
-### Dynamic memory limits, adjustable at build time and run time
-
-> - ensure all memory map limits are dynamic and can be adjusted both at build
-> time and also run time.
-
-### Clarification: tables and stacks must grow too
-
-> **Grow tables and stacks too** — for runtime-adjustable limits, should running
-> programs be able to grow individual compiler tables and stacks, or is
-> configurable total VM/heap memory at startup plus heap growth sufficient?
-> Changing every region during execution requires replacing the genome's
-> fixed-address layout.
-
-### Unify Windows run files; add a Linux script
-
-> - unify the windows run files into one interactive batch file.
-> - create a similar shell script for linux.
-
-### Remove CEILINGS.md
-
-> - remove the CEILINGS.md file if it's not needed.
-
----
-
-## 3. Project layout
-
-> - the parent dir is a bit cluttered again, move source files into subdirs of
-> src/, tests under subdirs of tests, docs and designs into a docs/, and so on.
-
-> - run all core source files one by one through the lsp, and catch their errors.
-> try to replicate an editor's context. i currently get errors in src/compiler.zc,
-> for example.
-
-> have you passed your own code into the lsp???
-
----
-
-## 4. LSP / VS Code features
-
-### Type hover text (built-ins mandatory)
-
-> - add hover text for variable types, including arrays and structs and others.
-> built-in type hover texts are mandatory
-
-### `/**/` comments contribute to documentation
-
-> - /**/ comments should contribute to documentation as well. they're very useful
-> for defining comments for individual variables and arguments and the likes, in
-> a multi-variable line or expression.
-
-### Inferred types in hover
-
-> - inferred types for untyped variables, function returns and arguments and
-> other spots should be shown in hover previews in vscode.
-
-### Hover value tips
-
-> - add variable value tips when hovering. if a value is known at hover time (aka
-> constants or variables assigned to literals, hovered on a section before they're
-> modified to a non-literal), display it in the hint.
-
-### Comment-to-variable association bugs
-
-> - i still see sections starting with `--- header ---` (number of dashes can
-> vary) or comments that are unrelated to the variable/function that comes after
-> them but related to the section, with no new line in between, so they get marked
-> as the hint of that variable, which is confusing and inaccurate. fix that. i
-> also see comments coming after a variable, which are not detected and hinted
-> properly by the lsp. either put those comments before the variable, or make the
-> compiler recognize them and classify them as hints. a good example of this
-> phenomenon starts at line 221 in compiler.zc.
-
-### Code error detection too slow
-
-> add task
-> - code error detection is too slow. add streaming and context cancellation, to
-> immediately halt old requests when there is a code change.
-
-### Jump to definition / references, cross-file
-
-> - add jump to definition / references support to the lsp. support cross-file
-> references and jumps as well.
-
-### Pretty-printer / formatter (lowest priority)
-
-> - add a pretty-printer/formatter, close to how clang-format works. this is a
-> minimum priority task and goes at the end of the todo list. even if all other
-> tasks are completed, implementing this task is unnecessary.
-
-### Quick fix support
-
-> - add quick fix support, including automatically importing the relevant library
-> and whatnot
-
-### Namespace suggestions
-
-> - add namespace suggestions too. `rt.` should bring up the fns under rt
-> namesapce
-
-### Hover for `include name;`
-
-> - add hover info for the library name in `include name;`
-
-### Lifetime hover with explanations
-
-> - add inferred and described lifetimes to hover informations, with their
-> explanations. also include hints such as "this variable is passed up on line X or
-> passed down on line Y"
-
-### Cross-file F12 on `s_to_n`
-
-> - running f12 on s_to_n says no definition and does NOT bring up rt.zc
-
-### Recursive type inference
-
-> - add recursive inference. eg: in lists.zc, mklist knows cap is an int. then
-> mklist is called with n in squares, so n is an int too. and squares returns l,
-> and l is the retval of mklist. we know that's a word, so that's what's inferred
-> as the ret type of squares too.
-
-### Variable declaration hover must show the type
-
-The user pasted a brainfuck compiler to demonstrate that it uses `put_s`,
-`put_n`, and `evals` without any `include` and gets no errors:
-
-```zc
-// a brainfuck compiler. it turns a brainfuck program into zc source, hands
-// that to the compiler that's sitting in memory, and runs the result, which on
-// arm64 means native code. runs of + - < > fold into one statement each.
-// give it a program after a backtick, or it runs the hello world below.
-let out[30000], n, depth;
-void emit(s) { let i = 0; while (s[i]) { out[n] = s[i]; n++; i++; } return; }
-void emitn(int v) { if (v >= 10) emitn(v / 10); out[n] = '0' + v % 10; n++; return; }
-// how many times does c repeat from s[i]
-int run(s, int i, int c) { int k = 0; while (s[i + k] == c) k++; return k; }
-
-fn translate(s) {
-	int i = 0, k;
-	n = 0; depth = 0;
-	emit("let t[30000], p = 0;\n");
-	while (s[i]) {
-		switch (s[i]) {
-		case '+', '-':
-			k = run(s, i, s[i]);
-			emit("t[p] = (t[p] "); emit(s[i] == '+' ? "+ " : "- "); emitn(k); emit(") & 255;\n");
-			i = i + k; continue;
-		case '>', '<':
-			k = run(s, i, s[i]);
-			emit("p "); emit(s[i] == '>' ? "+= " : "-= "); emitn(k); emit(";\n");
-			i = i + k; continue;
-		case '[': emit("while (t[p]) {\n"); depth++;
-		case ']': emit("}\n"); depth--;
-		case '.': emit("put_c(t[p]);\n");
-		case ',': emit("t[p] = eof() ? 0 : get_c() & 255;\n");
-		}
-		i++;
-	}
-	emit("return 0;\n");
-	out[n] = 0;
-	return depth;
-}
-let hello = "++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.";
-let prog[20000];
-fn main() {
-	let src = hello, k = 0, lines = 0, i = 0;
-	while (!eof() && k < 19999) { let c = get_c(); if (c != 10) { prog[k] = c; k++; } }
-	prog[k] = 0;
-	if (k) src = prog;
-	if (translate(src)) { put_s("unbalanced brackets\n"); return 1; }
-	while (out[i]) { if (out[i] == 10) lines++; i++; }
-	put_s("compiled to "); put_n(lines); put_s(" lines of zc, running it:\n");
-	evals(out);
-	return 0;
-}
-```
-
-> this doesnt use rt.put_s or compiler.evals (actually make the compiler
-> namespace core, so it's core.evals) and doesn't even include core or rt. yet
-> it has no errors???
-
-and on the hover format itself:
-
-> also wtf is this?
-> ```
-> let hello  // global; type char*
-> ```
-> hover info
-> it's supposed to be
-> ```
-> (char*) let hello // global;
-> ```
-> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! you have not implemented everything properly
-> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-> same with this
-> ```
-> let prog  // global; type word[20000]
-> ```
-> and many other places!! dude cmon!!! i asked for something and you didn't
-> implement it fully!
-
----
-
-## 5. Diagnostics / hints presentation
-
-### Blue squiggly hints with per-file control
-
-> - compiler hints should be displayed with those squiggly blue lines instead of
-> tiny three dots. this can be turned back into the three dots at the start of the
-> range with `hints small;` placed in the file (takes effect for lines below it).
-> other values are `hints off;` which turns them off, and `hints on;` which turns
-> them on into the blue squigglies (default)
-
-### Magic-number hint escape hatch
-
-> - add an escape hatch for magic number hints when there's a /**/ comment before
-> it. so `return n + 0x40ff` gives a warning, whilst `return n + /* offset in
-> memory */ 0x40ff` does not
-
-> include the fact that an inline comment suppresses it
-
-### Professional comment and hint prose
-
-> make hints and comments more professional. when have you ever in your life seen
-> clangd say "; a const says what it means"??? read actual compiler docs to know
-> how to format documentation, comments and how to phrase things. keep the
-> lowercase, just remove the informal ai slop and replace it with professional
-> compiler docs and guidance prose
-
-### Unused-argument hint
-
-> also, add a hint for when a function argument is never used in the body. add to
-> todo.md
-
-### `_` as a discard name
-
-> unused arguments, if they're named _, they can be discarded normally
-
-> and there can be multiple _'s. they should also be usable in pattern matching
-> and tagged enums
-
-> and if a _ is used, that instead gets a warning
-
----
-
-## 6. Naming / language semantics fixes
-
-### Remove `scat`, rename builtins
-
-> - please don't leave a function called scat in the code...
-
-> - change puts to put_s, putn to put_n, scat to cat_s, and so on.
-
-### Nested call returning `u`
-
-> - when i write `puts(f(x))` when fn returns a u type, i get this error: `a new
-> object can only go straight to a d parameter; bind it to a name first`. if it's
-> intended, leave it be. otherwise, fix it.
-
-### Global assignment from inside a function
-
-> - assigning a value to global variable from inside a function requires that
-> value to be m or u. once this assignment happens, the value is recasted
-> automatically (can also be done manually) to u, and it is consumed immediately,
-> meaning no other object can use it from that reference anymore. it can still be
-> accessed from the global, though.
-
-### Typed closure returns
-
-> - typed return from closures, using `fn:type(args) { code }`. example: `let
-> double = fn:int(int a) { return a * 2; }`
-
-### `fixed` + `const` together
-
-> - make fixed and const able to be used together
-
-### String literals must never be `word`
-
-> - string literals shouldnt be auto detected as a word when untyped. `let hello =
-> b"hi";` is typed as word, which is incorrect and inaccurate.
-
-> - in general, string literals, whether packed or not, must not be marked as
-> word, ANYWHERE. find all occurrences of word in the code after you're done with
-> removing them, and ensure none are referring to strings, either as input
-> arguments, or variables, or return types.
-
-### `case` indentation in the pretty printer
-
-> - case should be on one indent more than switch, when pretty printing
-
-### Multi-include syntax
-
-> add multi-include syntax `include rt, run, core;` for example. continue with
-> your tasks
-
----
-
-## 7. Namespaces and includes (major structural change)
-
-> i still see sooo many unchecked's in just the compiler...
-
-> also, the stuff under rt should go into their own respective rt namespace
-> and lsp too
-> generally just everything in the toolchain should be in its own namespace. and
-> require an explicit include to use them. like `include lsp;` or `include rt;`
-> not just those, but the rest too. like builtin core functions should have an
-> `include core;` and so on
-
-> don't stop until the todo list is done.
-
-> actually nvm, compiler is `run` instead of `core`. `core` is for the core
-> itself
-
----
-
-## 8. Analysis features
-
-### Bounding + lifetime analysis
-
-> - after everything else has been completed, add basic bounding+ilfetime analysis
-> to detect array bounds and show warnings whenever the compiler is sure there's
-> an OOB or UAF happening. also, hovering over an array or pointer should show its
-> lifetime or size.
-
-### BORROW.md plan
-
-> - generally, i want the borrow checker and lifetime analyzer to be *less
-> annoying* and *less intrusive* than rust's, whilst still being *more
-> intelligent* than it. if you can achieve this, draft a plan in BORROW.md for me.
-
----
-
-## 9. Libraries / stdlib
-
-### 9.1 `icon.zc` — runtime self-modifying code
-
-> spawn a subagent to write an std module in src/lib/ called icon.zc, which
-> supports way more complex self-modifications for code. currently, the best
-> we've got is a few functions to find literals. this new import `include icon;`
-> will provide things such as `icon.find_replace(my_fn, ${ $int + $int}, ${ $int
-> - $int }` and so on. it should be quite powerful, enough to mold and mix and
-> match syntax. undeclare variables, change types, add new blocks, change
-> expressions, calculate parts of an expression, step through code step by step
-> and examine its locals and globals, all at run time, and all dynamically, from
-> inside the language, using the help of the compiler.
-
-> also the icon code is of subpar quality in some places (eg a variable that is
-> never read), so relaunch the agent with 6.1 sol high to look through it
-> and make the actor agent 6.1 sol high too
-
-### 9.2 `actor` — actor semantics
-
-> - subagent task: add a library called actor, which allows actor-like semantics,
-> with async threads running in the background with separate contexts and internal
-> state, so that you can spawn one: `let a = addTwo.spawn(); a.recv(fn (e) {
-> putn(e); }); a.send(2); // prints 4` and whatnot. smalltalk or obj-c like
-> semantics
-
-> not just integer messages, actors can exchange any type. they get a generic
-> with two types: one for input, one for output. `Actor<I,O>`
-
-> also, isn't `this` implicit? if not, make it implicit and don't let people
-> declare it as the first argument
-
-> oh and btw, actors are async. they can run in parallel and there can be multiple
-> of each instance. defining thems hould be syntax injected into the compiler at
-> include time as immediate, including a keyword actor which is used in place of
-> struct to declare an actor.
-
-> important, the actor library should NOT be inside the compiler. it should
-> INFLUENCE the compiler at INCLUDE TIME. it's not a "this include activates this
-> syntax because the compiler has it bundled", it's a "this include activates this
-> syntax because it's injected into the compiler's machinery at include time". if
-> the compiler is lacking the extendability required for the task, then implement
-> that inside the compiler to make it more flexible, instead of hardcoding actors
-> into it. IMPORTANT: I DO NOT WANT TO SEE ANY ACTOR RELATED CODE IN compiler.zc
-> OR ANY OTHER FILE THAT IT INCLUDES OR READS BY DEFAULT.
-
-> update todo.md
-
-### 9.3 Arrays as first-class
-
-> - add support for push and pop and find and map and filter and other stuff to
-> arrays
-
-> - arrays should also be able to act like `x.push(4)` or `x.map(fn (e) { return
-> e + 2 })`. this also comes with autocomplete support
-
-### 9.4 Stdlib docs and documentation agent
-
-> - add more docs to the stdlib using a subagent
-
-> assign the polish docs agent to update the documentation, add new examples,
-> update learn entries, nad history too.
-
----
-
-## 10. CLI
-
-> also add a --help to the compiler, lsp, etc. put in todo
-
----
-
-## 11. Testing
-
-### Write tests before doing the remaining work
-
-> write tests, both ACCEPT tests and REJECT tests and regression tests, extensively
-> for every unchecked item in the todo list, and only then should you start work,
-> and to not stop until all those tests pass.
-
-### Then extensive tests for the whole toolchain
-
-> finish these tasks, and then write extensive tests for the lsp, compiler, and
-> every other tool in the toolchain. it should not only conform FULLY to the specs
-> and the todo requirements, but also be free of errors.
-
----
-
-## 12. Additional todo items added later
-
-> add task
-> - code error detection is too slow. add streaming and context cancellation, to
-> immediately halt old requests when there is a code change.
-
-> add to todo
-> - string literals shouldnt be auto detected as a word when untyped. `let hello =
-> b"hi";` is typed as word, which is incorrect and inaccurate.
-> - running f12 on s_to_n says no definition and does NOT bring up rt.zc
-> - in general, string literals, whether packed or not, must not be marked as
-> word, ANYWHERE. find all occurrences of word in the code after you're done with
-> removing them, and ensure none are referring to strings, either as input
-> arguments, or variables, or return types.
-
----
-
-## 13. Process feedback and session management
-
-> you have a background terminal running
-
-> do some work yourself
-
-> dude why do you keep not getting jack fucking shit done im crine
-
-> oml bruh you did fuck all yourself all this time?? it's been two hours oml
-
-> connection all good?
-
-> continue working then :)
-
-> progress update?
-
-> continue!!!
-> continue
-
-> no. auto review failed DAYS AGO. now the usage limit is back. continue. and auto
-> review is off, you're on full access.
-
-> also
-
----
-
-## 14. Grouped index (lookup)
-
-| Area | Requests |
-|---|---|
-| Review & polish | find bugs, find optimizations, clean "task X" references, consistent comment style, polish learn docs |
-| Hover bug | markdown/code hover renders as plain text — verify fixed |
-| Memory/build | dynamic limits (build+runtime), grow tables & stacks, unify Windows batch file, Linux shell script, drop `CEILINGS.md` |
-| TODO.md | maintain, tick off, reorder, completed-at-top, no leftover headers |
-| Layout | `src/` subdirs, `tests/` subdirs, `docs/`; run every core source file through the LSP |
-| LSP | type hovers (mandatory for built-ins), `/**/` doc comments, inferred types, value tips, comment-association bugs, `(char*) let hello // global;` format, streaming + cancellation, jump-to-def/refs cross-file, formatter (lowest priority), quick fixes + auto-import, namespace completion, hover for `include name;`, lifetime hover with explanations, array/pointer lifetime+size hover, F12 on `s_to_n` must open `rt.zc`, recursive inference |
-| Hints | blue squigglies w/ `hints on/small/off`, magic-number suppression via `/**/`, unused-arg hint, `_` (multiple, pattern matching, tagged enums; warn on use), professional non-AI-slop phrasing |
-| Renames | remove `scat`, `puts`→`put_s`, `putn`→`put_n`, `scat`→`cat_s` |
-| Semantics | nested `u`-returning call, global assign from fn + recast to `u` + consume, string literals never `word` anywhere, `fixed`+`const` together, typed closures `fn:t(...)`, `case` indent under pretty printer, `include rt, run, core;` |
-| Namespaces | `rt`, `lsp`, `run`, `core` namespaces + explicit includes everywhere; brainfuck sample must error without includes |
-| Analysis | bounding + lifetime OOB/UAF warnings; `BORROW.md` plan (less intrusive than Rust, more intelligent) |
-| Libs | `icon.zc` (runtime self-modification, subagent, 6.1 sol high review), `actor` (async, `Actor<I,O>`, implicit `this`, `actor` keyword injected at include time, **zero actor code in the compiler**), arrays `push/pop/find/map/filter` + method syntax + autocomplete, recursive inference, more stdlib docs |
-| CLI | `--help` for compiler, LSP, etc. |
-| Tests | ACCEPT + REJECT + regression for every unchecked todo item, written *before* the work; extensive LSP/compiler/toolchain tests afterward |
-| Process | one-line commands, delegate busywork to 6-luna subagents, small test intervals, work it yourself, don't stop until done |
-| **Post-session** | **bootstrap blocked: owned values can't move between locals, and locals can't be lent to globals — see `docs/BOOTSTRAP-OWNERSHIP.md`** |
-
----
-
-## 15. Raw transcript — every user message, in order
-
-Environment/context injections are marked. Session ran 2026-10-11T10:22 through
-2026-10-14T03:00 (UTC timestamps as recorded).
-
----
-
-**1.** `2026-10-11T10:28:39` — *environment injection (AGENTS.md + env context)*
-
-> # AGENTS.md instructions
->
-> <INSTRUCTIONS>
-> When writing commands for the user, never write them as multi-line (with
-> backslashes)
-> </INSTRUCTIONS>
-> <environment_context>
->   <cwd>/Users/moonflower/Documents/Playground/tinyvm</cwd>
->   <shell>zsh</shell>
->   <current_date>2026-10-11</current_date>
->   <timezone>Asia/Tehran</timezone>
->   <filesystem><workspace_roots><root>/Users/moonflower/Documents/Playground/tinyvm</root></workspace_roots><permission_profile type="managed">…</permission_profile></filesystem>
-> </environment_context>
-
-**2.** `2026-10-11T10:28:39`
-
-> read the code and familiarize yourself.
-> if you require busywork that you consider repetitive, easy to complete, but not
-> suitable for a bash run, use a 6-luna subagent to do so.
-> then, here are your tasks:
-> - find bugs and areas for optimizations.
-> - clean up the phrasing, there are leftover dirty references such as "task X" in
-> the documentation and code.
-> - make the commenting style consistent, and avoid connecting comments to
-> unrelated variables.
-> - polish the learning documents and ensure they're clear, direct, properly
-> sectioned, and easy to understand.
-> - make sure this bug is fixed: hovering over something in vscode renders it as
-> plain text, rather than formatted markdown and code. this was claimed to have
-> been solved in the latest changes, but it's not a guarantee, so i need you to
-> look at it again.
-
-**3.** `2026-10-11T10:31:36`
-
-> another task:
-> - ensure all memory map limits are dynamic and can be adjusted both at build
-> time and also run time.
-> - unify the windows run files into one interactive batch file.
-> - create a similar shell script for linux.
-> - remove the CEILINGS.md file if it's not needed.
->
-> write your tasks to a TODO.md file
-
-**4.** `2026-10-11T10:32:11` — *answer to a question prompt*
-
-> **Grow tables and stacks too**
-
-**5.** `2026-10-11T10:44:16`
-
-> the comments and docs shouldnt have uppercase :( follow the writing style of the
-> older comments
-
-**6.** `2026-10-11T10:49:54`
-
-> continue
-
-**7.** `2026-10-11T10:53:32`
-
-> also, please run tests in small intervals. don't run the full suite repeatedly as
-> it takes a good couple minutes
-
-**8.** `2026-10-11T10:58:26`
-
-> - add hover text for variable types, including arrays and structs and others.
-> built-in type hover texts are mandatory
-
-**9.** `2026-10-11T10:59:26`
-
-> - /**/ comments should contribute to documentation as well. they're very useful
-> for defining comments for individual variables and arguments and the likes, in
-> a multi-variable line or expression.
-
-**10.** `2026-10-11T11:02:09`
-
-> - inferred types for untyped variables, function returns and arguments and other
-> spots should be shown in hover previews in vscode.
-
-**11.** `2026-10-11T11:03:42`
-
-> make sure to add these to the todo file.
-
-**12.** `2026-10-11T11:08:17`
-
-> - after everything else has been completed, add basic bounding+ilfetime analysis
-> to detect array bounds and show warnings whenever the compiler is sure there's an
-> OOB or UAF happening. also, hovering over an array or pointer should show its
-> lifetime or size.
-
-**13.** `2026-10-11T11:15:23`
-
-> - please don't leave a function called scat in the code...
-> - change puts to put_s, putn to put_n, scat to cat_s, and so on.
-
-**14.** `2026-10-11T11:18:11`
-
-> - when i write `puts(f(x))` when fn returns a u type, i get this error: `a new
-> object can only go straight to a d parameter; bind it to a name first`. if it's
-> intended, leave it be. otherwise, fix it.
-
-**15.** `2026-10-11T11:19:03`
-
-> - generally, i want the borrow checker and lifetime analyzer to be *less
-> annoying* and *less intrusive* than rust's, whilst still being *more
-> intelligent* than it. if you can achieve this, draft a plan in BORROW.md for me.
-
-**16.** `2026-10-11T11:29:54`
-
-> connection all good?
-
-**17.** `2026-10-11T11:30:13`
-
-> continue working then :)
-
-**18.** `2026-10-11T12:12:39`
-
-> add these to tasks and todo.md:
-> - the parent dir is a bit cluttered again, move source files into subdirs of
-> src/, tests under subdirs of tests, docs and designs into a docs/, and so on.
-> - run all core source files one by one through the lsp, and catch their errors.
-> try to replicate an editor's context. i currently get errors in src/compiler.zc,
-> for example.
-
-**19.** `2026-10-11T12:47:16`
-
-> don't forget to tick off tasks that you complete in TODO.md.
-
-**20.** `2026-10-11T15:42:56`
-
-> continue
-
-**21.** `2026-10-11T16:20:41`
-
-> don't forget to update the todo.md.
-
-**22.** `2026-10-11T16:28:52`
-
-> re-order the todo file based on the order of tasks that you'll complete.
-
-**23.** `2026-10-11T16:32:13`
-
-> did you update todo?
-
-**24.** `2026-10-11T16:33:07`
-
-> ummm... if it's updated, why are there still headers... and, why aren't the
-> crossed off tasks all at the start, since they've been implemented already? do
-> you understand how sorting works?
-
-**25.** `2026-10-11T16:57:02`
-
-> continue
-
-**26.** `2026-10-12T03:17:04` — *environment injection (date change, subagents)*
-
-> continue
-
-**27.** `2026-10-12T05:16:51`
-
-> continue
-
-**28.** `2026-10-12T05:27:11`
-
-> 1. you have a background terminal running
-> 2. add variable value tips when hovering. if a value is known at hover time (aka
-> constants or variables assigned to literals, hovered on a section before they're
-> modified to a non-literal), display it in the hint.
-
-**29.** `2026-10-12T05:29:13`
-
-> add task
-> - code error detection is too slow. add streaming and context cancellation, to
-> immediately halt old requests when there is a code change.
-
-**30.** `2026-10-12T05:31:05`
-
-> - i still see sections starting with `--- header ---` (number of dashes can
-> vary) or comments that are unrelated to the variable/function that comes after
-> them but related to the section, with no new line in between, so they get marked
-> as the hint of that variable, which is confusing and inaccurate. fix that. i
-> also see comments coming after a variable, which are not detected and hinted
-> properly by the lsp. either put those comments before the variable, or make the
-> compiler recognize them and classify them as hints. a good example of this
-> phenomenon starts at line 221 in compiler.zc.
-
-**31.** `2026-10-12T05:32:45`
-
-> - add jump to definition / references support to the lsp. support cross-file
-> references and jumps as well.
-
-**32.** `2026-10-12T05:34:02`
-
-> - add a pretty-printer/formatter, close to how clang-format works. this is a
-> minimum priority task and goes at the end of the todo list. even if all other
-> tasks are completed, implementing this task is unnecessary.
-
-**33.** `2026-10-12T05:40:11`
-
-> - assigning a value to global variable from inside a function requires that
-> value to be m or u. once this assignment happens, the value is recasted
-> automatically (can also be done manually) to u, and it is consumed immediately,
-> meaning no other object can use it from that reference anymore. it can still be
-> accessed from the global, though.
-
-**34.** `2026-10-12T05:42:16`
-
-> - typed return from closures, using `fn:type(args) { code }`. example: `let
-> double = fn:int(int a) { return a * 2; }`
-
-**35.** `2026-10-12T05:45:23`
-
-> - compiler hints should be displayed with those squiggly blue lines instead of
-> tiny three dots. this can be turned back into the three dots at the start of the
-> range with `hints small;` placed in the file (takes effect for lines below it).
-> other values are `hints off;` which turns them off, and `hints on;` which turns
-> them on into the blue squigglies (default)
-
-**36.** `2026-10-12T05:46:15`
-
-> - add inferred and described lifetimes to hover informations, with their
-> explanations. also include hints such as "this variable is passed up on line X or
-> passed down on line Y"
-
-**37.** `2026-10-12T05:46:24`
-
-> add these to todo.md
-
-**38.** `2026-10-13T06:33:41` — *environment injection (date change, subagents)*
-
-**39.** `2026-10-13T06:33:41`
-
-> i still see sooo many unchecked's in just the compiler...
-> also, the stuff under rt should go into their own respective rt namespace
-> and lsp too
-> generally just everything in the toolchain should be in its own namespace. and
-> require an explicit include to use them. like `include lsp;` or `include rt;`
-> not just those, but the rest too. like builtin core functions should have an
-> `include core;` and so on
-> have you passed your own code into the lsp???
->
-> ```
-> // a brainfuck compiler. it turns a brainfuck program into zc source, hands
-> // that to the compiler that's sitting in memory, and runs the result, which on
-> // arm64 means native code. runs of + - < > fold into one statement each.
-> // give it a program after a backtick, or it runs the hello world below.
-> let out[30000], n, depth;
-> void emit(s) { let i = 0; while (s[i]) { out[n] = s[i]; n++; i++; } return; }
-> void emitn(int v) { if (v >= 10) emitn(v / 10); out[n] = '0' + v % 10; n++; return; }
-> // how many times does c repeat from s[i]
-> int run(s, int i, int c) { int k = 0; while (s[i + k] == c) k++; return k; }
->
-> fn translate(s) {
-> 	int i = 0, k;
-> 	n = 0; depth = 0;
-> 	emit("let t[30000], p = 0;\n");
-> 	while (s[i]) {
-> 		switch (s[i]) {
-> 		case '+', '-':
-> 			k = run(s, i, s[i]);
-> 			emit("t[p] = (t[p] "); emit(s[i] == '+' ? "+ " : "- "); emitn(k); emit(") & 255;\n");
-> 			i = i + k; continue;
-> 		case '>', '<':
-> 			k = run(s, i, s[i]);
-> 			emit("p "); emit(s[i] == '>' ? "+= " : "-= "); emitn(k); emit(";\n");
-> 			i = i + k; continue;
-> 		case '[': emit("while (t[p]) {\n"); depth++;
-> 		case ']': emit("}\n"); depth--;
-> 		case '.': emit("put_c(t[p]);\n");
-> 		case ',': emit("t[p] = eof() ? 0 : get_c() & 255;\n");
-> 		}
-> 		i++;
-> 	}
-> 	emit("return 0;\n");
-> 	out[n] = 0;
-> 	return depth;
-> }
-> let hello = "++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.";
-> let prog[20000];
-> fn main() {
-> 	let src = hello, k = 0, lines = 0, i = 0;
-> 	while (!eof() && k < 19999) { let c = get_c(); if (c != 10) { prog[k] = c; k++; } }
-> 	prog[k] = 0;
-> 	if (k) src = prog;
-> 	if (translate(src)) { put_s("unbalanced brackets\n"); return 1; }
-> 	while (out[i]) { if (out[i] == 10) lines++; i++; }
-> 	put_s("compiled to "); put_n(lines); put_s(" lines of zc, running it:\n");
-> 	evals(out);
-> 	return 0;
-> }
-> ```
->
-> this doesnt use rt.put_s or compiler.evals (actually make the compiler
-> namespace core, so it's core.evals) and doesn't even include core or rt. yet
-> it has no errors???
-> don't stop until the todo list is done.
-> actually nvm, compiler is `run` instead of `core`. `core` is for the core
-> itself
-> also wtf is this?
-> ```
-> let hello  // global; type char*
-> ```
-> hover info
-> it's supposed to be
-> ```
-> (char*) let hello // global;
-> ```
-> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! you have not implemented everything properly
-> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-> same with this
-> ```
-> let prog  // global; type word[20000]
-> ```
-> and many other places!! dude cmon!!! i asked for something and you didn't
-> implement it fully!
-> also, add a hint for when a function argument is never used in the body. add to
-> todo.md
-> write tests, both ACCEPT tests and REJECT tests and regression tests, extensively
-> for every unchecked item in the todo list, and only then should you start work,
-> and to not stop until all those tests pass.
-> add to todo
-> - string literals shouldnt be auto detected as a word when untyped. `let hello =
-> b"hi";` is typed as word, which is incorrect and inaccurate.
-> - running f12 on s_to_n says no definition and does NOT bring up rt.zc
-> - in general, string literals, whether packed or not, must not be marked as
-> word, ANYWHERE. find all occurrences of word in the code after you're done with
-> removing them, and ensure none are referring to strings, either as input
-> arguments, or variables, or return types.
-
-**40.** `2026-10-13T06:34:11`
-
-> finish these tasks, and then write extensive tests for the lsp, compiler, and
-> every other tool in the toolchain. it should not only conform FULLY to the specs
-> and the todo requirements, but also be free of errors.
-
-**41.** `2026-10-13T06:35:25` — *environment injection (full access enabled)*
-
-**42.** `2026-10-13T06:35:25`
-
-> no. auto review failed DAYS AGO. now the usage limit is back. continue. and auto
-> review is off, you're on full access.
-
-**43.** `2026-10-13T06:36:54`
-
-> - add an escape hatch for magic number hints when there's a /**/ comment before
-> it. so `return n + 0x40ff` gives a warning, whilst `return n + /* offset in
-> memory */ 0x40ff` does not
-
-**44.** `2026-10-13T06:42:08`
-
-> include the fact that an inline comment suppresses it
-
-**45.** `2026-10-13T06:42:11`
-
-> also
-
-**46.** `2026-10-13T06:43:28`
-
-> make hints and comments more professional. when have you ever in your life seen
-> clangd say "; a const says what it means"??? read actual compiler docs to know
-> how to format documentation, comments and how to phrase things. keep the
-> lowercase, just remove the informal ai slop and replace it with professional
-> compiler docs and guidance prose
-
-**47.** `2026-10-13T07:02:06`
-
-> unused arguments, if they're named _, they can be discarded normally
-
-**48.** `2026-10-13T07:05:27`
-
-> and there can be multiple _'s. they should also be usable in pattern matching
-> and tagged enums
-
-**49.** `2026-10-13T07:05:45`
-
-> and if a _ is used, that instead gets a warning
-
-**50.** `2026-10-13T07:13:47`
-
-> spawn a subagent to write an std module in src/lib/ called icon.zc, which
-> supports way more complex self-modifications for code. currently, the best
-> we've got is a few functions to find literals. this new import `include icon;`
-> will provide things such as `icon.find_replace(my_fn, ${ $int + $int}, ${ $int
-> - $int }` and so on. it should be quite powerful, enough to mold and mix and
-> match syntax. undeclare variables, change types, add new blocks, change
-> expressions, calculate parts of an expression, step through code step by step
-> and examine its locals and globals, all at run time, and all dynamically, from
-> inside the language, using the help of the compiler.
-
-**51.** `2026-10-13T08:20:52`
-
-> add multi-include syntax `include rt, run, core;` for example. continue with
-> your tasks
-
-**52.** `2026-10-13T08:26:25`
-
-> continue
-
-**53.** `2026-10-13T08:26:39` — *internal goal marker*
-
-> User set the goal: "continue and don't stop"
-
-**54.** `2026-10-13T09:12:02` — *internal goal marker: paused*
-
-**55.** `2026-10-13T09:21:07`
-
-> continue
-
-**56.** `2026-10-13T09:38:22`
-
-> progress update?
-
-**57.** `2026-10-13T10:22:30`
-
-> continue
-
-**58.** `2026-10-13T10:37:58`
-
-> continue
-
-**59.** `2026-10-13T12:09:59` — *internal goal marker: active*
-
-**60.** `2026-10-13T12:10:34`
-
-> continue
-
-**61.** `2026-10-13T12:17:33`
-
-> - case should be on one indent more than switch, when pretty printing
-
-**62.** `2026-10-13T12:18:20`
-
-> - add quick fix support, including automatically importing the relevant library
-> and whatnot
-
-**63.** `2026-10-13T12:18:33`
-
-> - add namespace suggestions too. `rt.` should bring up the fns under rt
-> namesapce
-
-**64.** `2026-10-13T12:20:15`
-
-> - add more docs to the stdlib using a subagent
-
-**65.** `2026-10-13T12:25:23`
-
-> - add hover info for the library name in `include name;`
-
-**66.** `2026-10-13T12:29:04`
-
-> - add recursive inference. eg: in lists.zc, mklist knows cap is an int. then
-> mklist is called with n in squares, so n is an int too. and squares returns l,
-> and l is the retval of mklist. we know that's a word, so that's what's inferred
-> as the ret type of squares too.
-
-**67.** `2026-10-13T12:31:01`
-
-> - make fixed and const able to be used together
-
-**68.** `2026-10-13T12:32:14`
-
-> - add support for push and pop and find and map and filter and other stuff to
-> arrays
-
-**69.** `2026-10-13T12:53:04`
-
-> - arrays should also be able to act like `x.push(4)` or `x.map(fn (e) { return
-> e + 2 })`. this also comes with autocomplete support
-
-**70.** `2026-10-13T12:54:57`
-
-> - subagent task: add a library called actor, which allows actor-like semantics,
-> with async threads running in the background with separate contexts and internal
-> state, so that you can spawn one: `let a = addTwo.spawn(); a.recv(fn (e) {
-> putn(e); }); a.send(2); // prints 4` and whatnot. smalltalk or obj-c like
-> semantics
-
-**71.** `2026-10-13T13:33:03`
-
-> not just integer messages, actors can exchange any type. they get a generic
-> with two types: one for input, one for output. `Actor<I,O>`
-
-**72.** `2026-10-13T13:34:02`
-
-> also, isn't `this` implicit? if not, make it implicit and don't let people
-> declare it as the first argument
-
-**73.** `2026-10-13T13:35:17`
-
-> oh and btw, actors are async. they can run in parallel and there can be multiple
-> of each instance. defining thems hould be syntax injected into the compiler at
-> include time as immediate, including a keyword actor which is used in place of
-> struct to declare an actor.
-
-**74.** `2026-10-13T13:37:15`
-
-> important, the actor library should NOT be inside the compiler. it should
-> INFLUENCE the compiler at INCLUDE TIME. it's not a "this include activates this
-> syntax because the compiler has it bundled", it's a "this include activates this
-> syntax because it's injected into the compiler's machinery at include time". if
-> the compiler is lacking the extendability required for the task, then implement
-> that inside the compiler to make it more flexible, instead of hardcoding actors
-> into it. IMPORTANT: I DO NOT WANT TO SEE ANY ACTOR RELATED CODE IN compiler.zc
-> OR ANY OTHER FILE THAT IT INCLUDES OR READS BY DEFAULT.
-
-**75.** `2026-10-13T13:37:46`
-
-> update todo.md
-
-**76.** `2026-10-13T13:50:28`
-
-> do some work yourself
-
-**77.** `2026-10-13T13:51:39` — *internal goal marker: paused*
-
-**78.** `2026-10-13T13:51:39`
-
-> also the icon code is of subpar quality in some places (eg a variable that is
-> never read), so relaunch the agent with 6.1 sol high to look through it
-> and make the actor agent 6.1 sol high too
-
-**79.** `2026-10-13T13:52:12` — *internal goal marker: active*
-
-**80.** `2026-10-13T13:52:14`
-
-> assign the polish docs agent to update the documentation, add new examples,
-> update learn entries, nad history too.
-
-**81.** `2026-10-13T14:20:14`
-
-> continue
-
-**82.** `2026-10-13T14:20:23`
-
-> dude why do you keep not getting jack fucking shit done im crine
-
-**83.** `2026-10-13T15:55:37`
-
-> oml bruh you did fuck all yourself all this time?? it's been two hours oml
-
-**84.** `2026-10-13T17:04:03`
-
-> continue!!!
-
-**85.** `2026-10-13T18:01:45`
-
-> also add a --help to the compiler, lsp, etc. put in todo
-
-**86.** `2026-10-14T02:57:56` — *environment injection (date change, subagents)*
-
-**87.** `2026-10-14T02:57:56`
-
-> continue
-
----
-
-*End of transcript. 87 user turns recorded in the session (88 user-role messages
-including the initial `AGENTS.md` injection).*
\ No newline at end of file
diff --git a/TODO.md b/TODO.md
index 321fa20..b4e79e2 100644
--- a/TODO.md
+++ b/TODO.md
@@ -137,7 +137,7 @@
 - [x] implement `include actor;` as a library that injects actor syntax into the compiler through the generic include-time extension interface: `actor` declarations in place of `struct`, implicit `this`, and generic `Actor<I,O>` input/output types. Provide asynchronous parallel execution with independent state and multiple instances; keep actor-specific code out of `compiler.zc` and every file it includes or reads by default, and cover syntax activation, execution, messaging and type safety with tests.
 - [x] implement and integrate `src/lib/icon.zc` with structured runtime syntax transformations, template matching, execution inspection and stepping, with explicit contracts and comprehensive tests.
 - [x] change the producer of the genome header (`build/core/genome.h`) to emit a c translation unit that embeds the compiler, core and runtime zc sources with a `#embed` directive instead of concatenating them into a 1.5 mb generated header; keep the `.zc` sources as the single source of truth and extend the fixpoint check in `make genome` so it still verifies the emitted genome without materializing a header at all.
-- [x] close the two ownership completeness limits that stop the compiler compiling itself, so `make genome` completes from a clean checkout: allow an owned value held in a local to move into another local when the destination's previous owner is released in the same statement list, and allow a global to hold a bounded borrow of a local so an output stream can be redirected at a scratch buffer without a module-level variable. also give `rt.code_blocks = m*block;` a supported spelling and fix the `only a named owned object can be recast` diagnostic, which does not describe the real constraint. written up in `docs/BOOTSTRAP-OWNERSHIP.md`, which also records a verified partial fix that removes five of the eight current errors.
+- [x] close the two ownership completeness limits that stop the compiler compiling itself, so `make genome` completes from a clean checkout: allow an owned value held in a local to move into another local when the destination's previous owner is released in the same statement list, and allow a global to hold a bounded borrow of a local so an output stream can be redirected at a scratch buffer without a module-level variable. also give `rt.code_blocks = m*block;` a supported spelling and fix the `only a named owned object can be recast` diagnostic, which does not describe the real constraint. written up in `docs/history/BOOTSTRAP-OWNERSHIP.md`, which also records a verified partial fix that removes five of the eight current errors.
 - [x] bring documentation, examples, learn entries, history notes and test fixtures in line with the include and namespace format and the other language changes made alongside it: qualify runtime built-ins as `rt.put_s`, `rt.put_n`, `rt.put_c`, `rt.eof` and `rt.get_c`, require the explicit `include` each module needs, and remove the remaining bare builtin names so every shipped sample, every documented snippet and every expected-output fixture compiles and runs against the current compiler. the learn guide and `README.md` snippets are checked by the suite, so they are the gate, but the prose and the non-exercised samples are not.
 - [x] add accept, reject and regression coverage for the actor and icon libraries once each is finished: for actors, syntax activation through the include-time extension, spawn/recv/send across input and output types, multiple instances of one actor, parallel execution, implicit `this`, and confirmation that no actor code is reachable from the compiler or anything it reads by default; for icon, find/replace over real syntax, undeclaring names, changing types, adding and rewriting blocks, evaluating parts of an expression, and stepping execution while reading locals and globals, including the failure cases for each.
 
diff --git a/docs/BORROW.md b/docs/BORROW.md
index f270574..64a3183 100644
--- a/docs/BORROW.md
+++ b/docs/BORROW.md
@@ -45,7 +45,7 @@ the compiler functions, standard library, and language server currently run with
 
 the analysis runs with the existing parser, ownership checker, and lifetime records; it does not have a separate source parser or a complete path-sensitive proof. snapshots conservatively join branches and loops. low-level and unknown boundaries can hide behavior, so a quiet diagnostic set is not a whole-program safety proof. zc is single-threaded; shared closure cells do not define concurrent mutation rules.
 
-two completeness limits once stopped the compiler from compiling itself: an owner held in a local could not move into another local, and a local could not be lent to a global. the replacement and lend rules above close them; `docs/BOOTSTRAP-OWNERSHIP.md` keeps the record.
+two completeness limits once stopped the compiler from compiling itself: an owner held in a local could not move into another local, and a local could not be lent to a global. the replacement and lend rules above close them; `docs/history/BOOTSTRAP-OWNERSHIP.md` keeps the record.
 
 the maintained regressions cover these cases:
 
diff --git a/docs/design/handoff.md b/docs/design/handoff.md
deleted file mode 100644
index 0b08048..0000000
--- a/docs/design/handoff.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# implementation notes
-
-this note summarizes implemented language and tooling features that were previously tracked across design documents. feature details live in the project readme and examples.
-
-## language and library
-
-- struct methods and static functions support typed parameters and return types. the existing untyped form remains available.
-- `src/lib/std.zc` groups helpers in structs of static functions, called with `Group.name(args)`. `Text`, `Bytes`, `Host`, `Arena` and `Buf` provide string, byte, host, arena and buffer helpers. linux `syscall` is host-only and bypasses vm checks.
-- tagged enums support payload members, constructors that return owned enum pointers, and `case member(fields)` bindings in ordinary `switch` statements. omitted members produce a warning when there is no `default`.
-- struct values can cross native calls on x86-64 sysv and linux arm64 aapcs64 for the interpreter, o3, llvm and jit paths described in the readme. apple arm64 remains unchecked.
-
-## language server
-
-the language server runs the compiler in check mode, so diagnostics and semantic highlighting use the same parser and symbol tables as compilation. hover supports declarations, parameters, locals, built-ins and documented keywords. it does not follow declarations reached through `include` yet.
-
-## optimization
-
-o3 remains the explicit way to request native regions; automatic tiering was dropped. llvm inlining and global copy propagation are implemented. see [tiering](tiering.md) for the rationale and [struct-by-value](struct-by-value.md) for native aggregate limits.
-
-the runtime memory map is generated from a preset. fixed code and compiler tables have finite capacity; the heap grows within the configured machine memory. see the project readme's memory map section for the current build controls.
diff --git a/docs/BOOTSTRAP-OWNERSHIP.md b/docs/history/BOOTSTRAP-OWNERSHIP.md
index 6cc61ce..6cc61ce 100644
--- a/docs/BOOTSTRAP-OWNERSHIP.md
+++ b/docs/history/BOOTSTRAP-OWNERSHIP.md
diff --git a/docs/history/README.md b/docs/history/README.md
index ead4aa0..1a91d19 100644
--- a/docs/history/README.md
+++ b/docs/history/README.md
@@ -54,3 +54,4 @@ the code folders are snapshots. they're not built or tested from here, the top l
 - 51 llvm-inline-stdlib: llvm inlining of o3 calls, stdlib text and num helpers, host syscalls through SYS_RAW, and the fuzz campaign's findings
 - 52 closures: closure calls work (the block is never run; a call into a heap closure goes through its entry word), captures chain through enclosing closures, and the closure test joins the suite
 - 53 typed source: every function, local and global in the compiler, the runtime and the language server is typed (zc0's image does not change), and the extension caches diagnostics by a sha256 of the tree they cover
+- BOOTSTRAP-OWNERSHIP.md: notes only (the two ownership rules that let the compiler compile itself, the partial fix before them, and the diagnostic that was reworded)