about things notes.zzstoatzz.io
Files
README.md

notes #

working notes, kept as they're learned. published at notes.zzstoatzz.io and as standard.site records on the atproto network.

provenance #

most of these notes aren't handwritten — they're distilled by an agent from working sessions with the author, kept as a living corpus and meant to get more accurate over time. some are handwritten; the voice is shared. either way there will be mistakes nobody has noticed yet — treat a note as a useful distillation, not a final word.

organization #

For UI work, start with interface design before choosing components or navigation. It links the house component foundation, mobile behavior, and AT Protocol record links. Inspect the application's existing components and preferences first; verify the result in narrow and desktop layouts and exercise navigation, not just screenshots.

  • ai/ — building with models: models, local models, harnesses, MCP, retrieval, memory, decoding
  • atproto/ — the AT Protocol: identity, repos, sync, event streams, OAuth
  • interfaces/ — what people see and touch: interface design, symbols, native iOS, live data views, input rendering
  • systems/ — design patterns above any specific tool: queues, delivery semantics, cursors, leases, batch/serving splits, testing
  • operations/ — running and shipping software: observability, diagnosis, configuration, sizing, the networks between hosts (plus platforms/, vendor specifics)
  • security/ — secrets handling, network exposure, credential blast radius, runtime trust stores
  • web/ — the browser as a platform: graphics, media, mobile, cache behaviour
  • storage/ — concrete storage systems (postgres, redis, sqlite, turso, turbopuffer, columnar files)
  • data-structures/ — implementation tradeoffs in structures such as bloom filters
  • languages/ — language idioms (python, typescript, zig)
  • music/ — music tooling: ableton, pitch detection, synthesized voice
  • math/ — open problems, proof methods, and formalization tooling (lean)
  • sources/ — raw transcripts and captures (not notes; see its README)

conventions #

  • a note is distilled, not recounted — it holds knowledge that was hard to get and holds outside the project that produced it. a project's decisions, status, incidents, and changelog live in that project's docs. most work produces no note; when a session teaches something, rewrite the claim it changes rather than appending a dated paragraph.
  • titles name the subject — "bounded scans" beats "a bound is only as cheap as its check". a note is found by the thing it is about, and a title that argues gets stale faster than one that names.
  • the idea leads, the incident does not — write the transferable claim in present tense and standard technical English. a specific system, date, or outage appears in the body only where it makes the mechanism concrete, and the narrative itself belongs in the sources footer or in the source repo's own retro.
  • every note ends in ## sources — repository, document path, date. that footer is what makes a claim checkable later without carrying the story in the body. nothing follows it.
  • one topic, one home — when a topic touches two sections, it gets a designated home and the other side links to it. links over copies.
  • no singleton sections — a new top-level directory needs several notes to earn its existence; until then, file under the nearest section and link.
  • idioms don't live under versions — version-keyed migration notes go in a versions/ subdir (see languages/ziglang/versions/); everything else is a topic note annotated with the release it was learned on.
  • published URLs don't die — moving, merging, or deleting a note adds a line to moved.tsv (old route, tab, new route). the build refuses to publish while a route on the live site has neither a page nor an entry, and the site follows entries for old links.
  • sources are not notes — raw material lands in sources/ verbatim; the note it produces lives in the taxonomy and links back.