rename ASKLIST.md to TASKLIST.md

the ask list is the task list; there was no reason to carry a separate name.

1 files changed, 1203 insertions, 0 deletions

diff --git a/TASKLIST.md b/TASKLIST.md
new file mode 100644
index 0000000..8d081d9
--- /dev/null
+++ b/TASKLIST.md
@@ -0,0 +1,1203 @@
+# 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