replaced with phrasings that say the specific thing each one was
gesturing at (freshness floor, breaks builds, core finding).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

written while porting gloom to zig for stream's jss segment archive:
the contract, why cache-line blocking wins, gloom's OHBF construction,
and where it earns its keep in jetstream v2 segment footers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

short sentences (<=25 words), one idea per sentence, active voice, simple
tenses, no contractions, no idioms or metaphors. quoted citations kept
verbatim. content and claims unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

this was published to the PDS by accident as a site.standard.document on
the leaflet publication, so it showed up in readers. the record opened with
a blockquote reading "this is a draft."

the record has been deleted. no copy of the source markdown existed anywhere
on disk, so the PDS record was the only one — kept here as rendered markdown
plus the raw record, with frontmatter noting where it came from.

sources/ is in the publisher's EXCLUDE set, so this cannot be republished by
accident.

two additions from the july 2026 pub-search builder arc:
- serving-from-snapshots gains the off-box lesson (a batch layer needing a
tight watchdog is on the wrong infrastructure) and the gate/watermark
lesson (pin a column whose advancement implies real change)
- reconcilers-own-config: hand edits to reconciled objects are already
reverted; the 5400s watchdog fix that a deploy silently undid

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the build now emits llms.txt (an index per llmstxt.org: title, the
provenance note, one link per note as raw markdown) and llms-full.txt
(the entire corpus in one file, sections separated with source-url
comments) — so 'curl notes.zzstoatzz.io/llms-full.txt | pbcopy' is the
whole get-the-corpus-into-context workflow.

justfile: build / copy (curl the published corpus to clipboard) /
copy-local (uvx copychat over the working tree, uncommitted edits
included).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

masked-failure and policy-enforced-by-accident were carrying fake-deep
freight: metaphor closers ('buy the silence back', 'pay the second half
of the bill', 'silence is data', 'until it wasn't'), filler ('which is
precisely the problem', 'in a different costume'), and — worst — a
paragraph of invented hypothetical examples presented as if observed.
both rewritten to the incidents, the mechanics, and the canon citation,
with one plainly-stated general claim each. the useful additions that
survived: the audit question (what code enforces each written policy,
and does it know it's doing policy) and the verbatim retro diagnostic.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

honed against the canon rather than presented as house wisdom:

- serving-from-snapshots: the builder/manifest/overlay shape IS the
lambda architecture, and typeahead's 210s q=bsky incident is kreps'
two-systems critique collected as a bill (plus nygard's unbounded
result set). what's ours: overlay-is-authoritative and batch-cadence-
is-load-bearing
- masked-failure: the 13-day silent ingester wedge and 'the cutover
removed the anesthesia', grounded in cook's how-complex-systems-fail
(latent failures, degraded mode is normal). the trade stated plainly:
reliability features convert failures from loud-and-small to
silent-and-large; watchdogs/heartbeats/staleness alarms buy it back
- policy-enforced-by-accident: the bridgy door — a ban enforced for
months by a dependency's verification strictness, silently repealed
by a deliberate fallback. hyrum's law pointed inward. the apparently
unnamed one of the three

convoy-phenomenon material deliberately NOT its own note (blasgen/gray
named it in 1977); it stays a citation where it appears.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

read the opening of every page in the corpus (and the bodies of the
flagged ones). the recurring defect: project names — zds, zat, zlay,
pdsx, pub-search, phi, marvin, letta, docket, burner-redis, otel-zig,
leaflet, Atmos — used as if the reader already knows them. every first
mention per page now carries a link and a clause saying what the thing
is, in the page's own register (the 'from [project/file]' attribution
lines get a one-time gloss; concept pages introduce their evidence
systems up front; the cost log gets one orienting line instead of
thirty glosses).

also corrected two fabricated-from-memory urls found by verification:
tranquil-pds lives at tangled.org/tranquil.farm/tranquil-pds, pydocket
at github.com/chrisguidry/docket.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

new pages, each grounded in shipping zig code:
- repo-writes: per-DID lanes + phase profiling, lazy MST, rev
monotonicity under clock skew, first-appearance repo_rev, swap
preconditions under the lock, service auth
- car-export: reachability-based getRepo (with the update/delete-then-
export regression and 1.4/16.8/95.7ms numbers), full-vs-incremental
root CIDs, backfill concurrency isolation, verified imports
- blobs: raw-leaf CIDs, bytes/metadata split, reference-counted public
authorization via expected_blobs, defensive serving headers
- serving-event-streams: precomputed frames, durability-before-emission
(the 2,670-producer OOM), pull-based fan-out, the v1 cursor contract,
drop-count-never-crash, counters-prove-checks
- oauth/dpop: stateless HMAC nonces, the use_dpop_nonce double channel,
proof verification field by field

enriched in place: firehose.md's cursor section replaced (the old text
described the legacy ack model; the real contract silently clamps
too-old cursors and replays inclusive-overlapping), sync-verification
gains stream's first-slice stance + zds's sync-1.1 emission fields,
identity gains PLC operations, lexicons gains what validation actually
checks, auth gains server-side sessions + service auth.

pds-implementation.md dissolved: concept content redistributed above,
zds project ops (layer boundaries, smoke ritual, zig zen) belong in the
zds repo. README index regrouped into identity/write-path/streams/auth
clusters with zds + stream added as sources.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

a curated recap of a chat is still event-shaped, so it lives with its
raw material rather than among the atproto concept notes. sources/ stays
hosted-but-unlisted and unpublished.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the ai groups were retrospectives keyed to projects (pub-search's search,
phi's memory, the marvin bot's history) — project notes belong in those
repos. regrouped the way the content actually clusters:

- ai/retrieval/ (was embeddings/): asymmetric embedding, reciprocal rank
fusion, synthesize-before-injecting — query-time mechanics, projects as
evidence within
- ai/memory/ (dissolves persistent-agents/): message-archives (the
transcript layer across marvin's three eras + phi's network-as-archive)
and deliberate-and-background-writes (the two write paths, phi/letta
convergence, write-time curation, the integration-surface lesson)
- ai/cluster-the-2d-projection: loose note until a second cartography
note earns a group
- agentic-harness -> harness-weight: the finding is the page, Pi is the
evidence
- databases/ -> storage/ (redis was already stretching 'database');
turbopuffer-in-production moves in as storage/turbopuffer.md — vector
store operations are storage operations

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

'fuse ranks, not scores' -> 'reciprocal rank fusion for hybrid search';
'cluster the projection, not the vectors' -> 'cluster the 2d projection'.
half of each old title was spent negating an alternative instead of
naming the method. scanned every page H1 in the corpus for the pattern;
the only remaining instance is sargable-joins (the author's own, where
the second clause names the specific anti-pattern).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

'letta lasted ten hours' read as a verdict; the reality is ongoing
tinkering and genuine interest (void, the two-memory-type model). the
note is now 'the slack bot rebuilt its memory three times' — the letta
episode is one day in that history, read narrowly as an
integration-surface lesson (an SDK lifecycle bug, nothing about the
memory model). added the 2.x Application state-object lineage (the
JSON-patched maze) as the era's own answer to stateful agents, and the
conscious/background memory parallel between letta's model and phi's
save_memory vs extraction/residue.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

two notes from primary sources:

- letta-lasted-ten-hours: the marvin slack bot's memory across three
major versions (TTL cache -> prefect JSON blocks of assistant threads
-> pydantic-ai message archive in a filesystem/GCS block + turbopuffer
user facts), and the 2025-12-09 letta episode — adopted 13:32, went
all-in 15:15 (deleted the home-rolled facts store), reverted 23:20
when the SDK's __aexit__ crashed the event loop. commit shas cited
- phi-memory-in-parts: phi's persistence as a table of four stores plus
the passes that do the framework-shaped work (extraction ->
reconciliation, synthesis before injection, residue, trust labels),
and the two properties that fall out: per-layer inspectability and
degrade-don't-crash

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- auth.md conflated the base 'atproto' OAuth scope with
transition:generic. corrected with the plyr.fm evidence: early relay-era
config requested 'atproto transition:generic repo:...', current
resolved_scope is granular repo/blob/permission-set scopes with
transition:generic surviving only in test mocks. 'atproto' was always
the sign-in floor
- page headings move out of the left tree into a right-hand 'on this
page' column (≥1280px; hidden below): left nav is pages and groups
only, so it stays shallow and scannable

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the notes i wrote yesterday were dense with the 'X, not Y' construction
and abstract category talk — the exact tic phi's posting-inventory
prompt bans. retrieval-is-not-context.md was the worst: even the title
was the tic, and the body discussed categories instead of the incident.
rewritten as synthesize-before-injecting.md, leading with the concrete
failure (stale 'waiting on the relay fix' next to fresh 'it shipped',
both scored relevant) and the actual mechanics. rhetorical contrasts
cut everywhere ('an index, not a database', 'a tuning surface, not a
constant', 'a domain section, not a technology one'); factual technical
contrasts (hdbscan runs on the umap output, not raw vectors) kept.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

on the site home and the repo README: most notes aren't handwritten,
they're distilled from working sessions and meant to get more accurate
over time — a useful distillation, not a final word. deliberately does
NOT claim everything was reviewed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

corpus-wide audit (97 files, three reviewers briefed on the defect class
from the local-models fix) found five passages of narrative residue;
all verified in context and rewritten plainly:

- tailscale.md: 'validated by field writing (mmatt's post)' leaned on a
third party's authority the note didn't need — its own repo is the
evidence; the writeup is corroboration
- firehose-as-sound.md: three same-domain rate samples had been
generalized into a law about 'things humans build at human scales';
scoped back to the observation
- sdk-affordances.md: the truncated aphorism 'no is temporary.' replaced
with the actual reasoning (declining is reversible, a public API is
forever)
- mst-hot-paths.md: dropped the scare-quoted 'Zig is faster than Go'
strawman; the representation lesson stands on its own
- logfire-clients.md: removed mind-reading ('the author clearly knew
this was coming'); the observable fact stays

everything else held: bold rules backed by in-note numbers, first-person
war stories with specifics, grounded opinion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the README headline debated a strawman ('never local can't') the note
never set up and leaned on a borrowed third-party framing. rewritten to
state what the failures actually traced to. same treatment for the two
echoes in tool-calling.md; its evidence-backed rule stays.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

taxonomy work informed by pub-search's vector index: for each note we
asked which other notes are its semantic neighbors. findings: local-models
is a perfect island (100% self-cohesion) — mis-leveled, not scattered;
MCP is its own island inside protocols with zero cross-ties to
local-models, so it STAYS in protocols (the initial move out was reverted
— MCP is a protocol first).

new ai/embeddings/: five claim-titled notes distilled from code running
on this machine, not speculation —
- asymmetric-embedding (pub-search's input_type discipline + doc prep)
- fuse-ranks-not-scores (RRF mechanics, independent failure, the
fallback-stampede scar)
- retrieval-is-not-context (phi's synthesize-before-inject, supersession,
trust ladder)
- turbopuffer-in-production (id limits, schema evolution, cold
namespaces, stale attributes, the dummy-vector scan idiom)
- cluster-the-projection (phi-atlas: umap then hdbscan, the noise-label
landmine, promotion pressure from cluster geometry)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the hash route was the raw file path, which leaked .md into shareable
URLs and broke on directory-style links (…/atproto/ normalized to
atproto/.md, the reported 'failed to load'). routes are now canonical
and layout-free: a note is its path sans .md, a directory is itself
(its README renders), home is bare. rendering tries route.md then
route/README.md. legacy #foo.md and trailing-slash links normalize to
the same route, so nothing already shared breaks. relative links in
content resolve against the actual doc file (README vs note siblings
resolve differently). routeFor covered by a 10-case check incl. the
reported inputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

raw captures aren't notes — the writeups link to them, but they don't
belong in the sidebar as a peer section. files still copy to
/docs/sources/ so those links resolve.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- fastmcp.md rewritten as one coherent note: fixed heading hierarchy,
running folded into basic usage, concrete context/middleware examples
under key features, response-size protection kept. dropped 'tools vs
resources' (duplicated the section README) and 'entry points'
(duplicated project-setup.md's existing section verbatim)
- claude code plugins is host-side packaging, not a server-framework
topic: own note (protocols/MCP/claude-code-plugins.md), indexed
- ripped out the @filterable/jmespath pattern everywhere (deprecated by
the author): gone from fastmcp.md; typing.md keeps its ParamSpec/
overload/Annotated lessons on a neutral traced-decorator example

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- a section without a README now generates a nested tree index (matching
the sidebar) instead of a flat dump of every leaf — 'languages' was 55
unordered bullets
- languages/python/ecosystem/mcp.md merged into protocols/MCP/fastmcp.md
(the python note was the richer half: middleware, decorator patterns,
response-size protection, plugins, entry points — now under 'in
practice'); python README points across. one topic, one home, actually
applied this time

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

survey findings (all 99 notes read) mapped to a light restructure:

- languages/ziglang: 0.15/ and 0.16/ dissolved — timeless idioms move to
topic files at the section root (annotated with the release they were
learned on), genuinely version-keyed notes go to versions/
(migration-0.16, format-0.15, io-0.15). the twin testing.md and
comptime.md pairs are merged. observability/ (two zig implementation
notes) becomes languages/ziglang/observability/
- architecture/home-infra/: the cost/home-box cluster (infra-cost-
optimization + cost-declaration + tailscale) — previously spread across
three sections and held together by non-rendering [[wikilinks]] — gets
one home; all wikilinks converted to real markdown links
- sources/: raw transcripts are captured, not composed — they move out of
the taxonomy (writeups stay as notes, linking back). excluded from
standard.site publishing for the same composed-vs-captured reason
- protocols/atproto: applications/bluesky/ (4 levels for one note)
flattens to bluesky-notifications.md
- new root README states the conventions (claim titles, one-topic-one-home,
no singleton sections, idioms-not-versions, sources-are-not-notes);
every internal link verified resolving; networking/ and observability/
sections dissolved (7 sections -> 6)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

the lexicon is explicit that textContent 'should not contain markdown or
other formatting' — flatten it for indexers, and carry the raw markdown
in the content union as at.markpub.markdown (flavor gfm, renderingRules
marked) for renderers. edits now bump updatedAt while publishedAt keeps
first-publish time. one-time full rewrite of the 99 documents.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- manifest now carries the directory tree (dirs as nodes linked via their
README) instead of flat 'redis/streams' labels; sidebar renders it
recursively with collapsible sections (caret toggles, link navigates)
- scripts/publish-standard-site.mjs: site.standard.publication 'notes' +
one site.standard.document per note on the operator's PDS, zat.dev
style (stable rkeys, upsert-then-prune) but diff-aware: unchanged notes
produce no write and publishedAt survives edits, so indexers like
pub-search see real recency, not republish noise. scoped to this
publication's site uri — other site.standard records are never touched
- CI publishes after the wisp deploy when ATPROTO_APP_PASSWORD is set

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

zat.dev pattern: a no-framework client shell (marked + prism, vendored)
renders the markdown tree; scripts/build-site.mjs walks the section
directories into site-out/ with a manifest for the sidebar; tangled CI
deploys to wisp on every push to main — so operator pushes and merged
PRs (including phi's, via the tangled MCP) both publish.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- onEnd held the processor mutex across the span deep-copy → convoy under
concurrency (fixed in otel-zig zig-0.16 3dd08a8); rule: never alloc under a
shared lock
- how to localize "slow endpoint, fast queries": isolate machine/pool/alloc/
queries; superlinear scaling = lock contention not CPU
- mutex choice for processors that own a real export thread on 0.16
- otel-zig trunk (0.15) vs zig-0.16 line — which one downstream actually pins

From the consolidation that moved every first-party zig project onto one
canonical websocket.zig (tangled v0.1.8) and zat v0.3.8.

- new languages/ziglang/websocket/: fork lineage, the WorkerState.init
argument-order divergence from upstream, v0.1.8 = v0.1.7 + 0.16 test
harness, consumption notes.
- 0.16/io/patterns.md: argument ordering — std leans allocator-before-io
(~104:4 in 0.16.0) for constructor-shaped fns, with a reproducer.
- build/dependencies.md: one-version-per-package-per-graph (name+fingerprint
collisions, leaf-up convergence), zig-pkg/ cache hygiene, tangled.org tag pins.
- ziglang README: link the websocket subdir, repoint websocket.zig to the fork.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Corrects the roadmap: the "move the hub to heavypad" plan was the wrong
mechanism. Serving a ~400KB page from home behind the EU edge meant a US->DE->US
DERP-relayed round trip (~12s; render itself was 12ms). Lesson: serve bytes from
the edge, sync the ~4MB of data. Records the edge-serve+sync architecture,
CardTable pagination, the prompt-caching hit-rate story, typeahead-index Phase 2
(+ ISP cadence caveat), and the keep-main-checked-out process lesson.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- networking/tailscale.md: operational playbook + gotchas + skill landscape
- architecture/infra-cost-optimization.md: cost system, EU-migration lesson, home
offload roadmap, and the completed all-deployments migration + its gotchas
- protocols/atproto/cost-declaration.md: first-principles sketch of a standard
atproto cost-declaration protocol

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- expand local-models/ into running local LLMs agentically: tool-calling.md (the
serving-layer wall, per-engine ollama quirks, does-it-tool as the diagnostic,
gemma-4+mlx_vlm returning structured tool_calls) and agentic-harness.md (Pi as a
lean headless coding agent, lean-beats-heavy, models.json local provider, eval
loop). README ties it together with the "engine+model generation, not local-can't"
finding (Vicki Boykis's point).
- rename the vague systems/ -> architecture/ (its own README already called it
"architectural patterns"); no inbound links to fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

a test with comptime-known inputs may evaluate the function at compile time, so a
logic bug becomes a compile error (not a runtime FAIL) and runtime-only behavior
isn't exercised. force runtime with `var x = ...; _ = &x;`. caught while wiring
`zig test` as the objective oracle for the zigman eval harness.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- 0.16/cli.md: terminal CLI patterns — stdout/stderr split, broken-pipe
handling, http.Client.fetch, pager/browser via process.spawn pipe, isTty
- build/distribution.md: cross-compile matrix, static-linking facts, strip,
and why static hosts need .tar.gz (they 404 extensionless binaries)
- migration.md: trimLeft->trimStart, and the `zig env` std_dir-relative-to-HOME
grepping gotcha
- add zigman to the sources table

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

turso.md: pre-existing draft committed for the first time. Adds a
"query plans: scan the small table, search the big one" section
covering the SCAN-bad-table → subquery-in-FROM rewrite pattern that
dropped leaflet-search's leaderboard cache reads ~6x.

http-client.md: documents the HEAD-redirect panic at Client.zig:1826
that crash-looped leaflet-search's reconciler for 5+ hours. The
panic is hard (.? on null) — can't be caught. Workarounds listed.

Captures the notes from building tangled.org/zzstoatzz.io/redis,
burner-redis, and docket — split semantically rather than per-tool so
the patterns live alongside the protocol they belong to.

new top-level systems/ exists for architectural patterns that aren't
tied to a single tool or language (background-tasks is the first
entry; future: leader election, distributed locks, event sourcing).

contents:
- databases/redis/README.md — protocol overview, RESP types
- databases/redis/streams.md — XADD/XREADGROUP/XACK/PEL/XAUTOCLAIM,
docket's queue/parked/runs structure
- databases/redis/eval-lua.md — atomic scripts, Lua 5.1 specifics,
redis.call vs redis.pcall, return-value mapping, embedded engines
- databases/redis/embedded.md — the burner-redis pattern, dual-backend
story, what doesn't fit in-process
- systems/README.md — what the new namespace is for
- systems/background-tasks.md — celery → sidekiq → arq → pydocket →
docket lineage; at-least-once contract; perpetuals; future scheduling
- languages/ziglang/0.16/per-command-arena.md — the protocol-client
lifetime trick we used to fix the redis-client xreadgroup leak
- languages/ziglang/0.16/ziglua-ffi.md — embedding Lua 5.1 via
ziglua, the upvalue closure pattern, 5.1 vs 5.4 API gotchas

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

a single sibling to firehose.md framing the perspective fig
articulated on bsky: that atproto's daily request/event rates
(150-450 ev/s range) happen to overlap precisely with the most
expressive part of the audible-frequency band, which suggests
treating relay rates as voices in a chord.

content is idea-first: the observation, why the mapping works
(numbers table), what becomes hearable that isn't visible in
dashboards (chords, beats, detuning, silence, stability), what
it doesn't tell you (it's measurement, not diagnosis), and a
brief footnote pointing at relay-eval/sonify as one realization
plus the zig pattern underneath.

deliberately NOT in observability/ — that folder is for
telemetry-instrumentation references, not for atproto-specific
perspectives.

this file didn't belong in observability/ — that folder is for
technical references on instrumenting code with telemetry
(logfire client architecture, etc.), not for project writeups
about specific deployed webpages.

the zig pattern note added in 14a8bdc (languages/ziglang/0.16/
atomic-rate-meter.md) stays — it's a reusable pattern in the
right structural shape.

two notes from building relay-eval's /sonify page:

- observability/sonifying-the-firehose: the technique itself.
why audio works as observability (ear is great at picking out
one off-pitch voice in a chord), the 1:1 Hz=ev/s mapping
rationale, the architecture that makes server bandwidth scale
with relay count not viewer count, what the audio reveals and
what it doesn't (it's measurement, not diagnosis).

- languages/ziglang/0.16/atomic-rate-meter: the zig-specific
pattern underneath. lock-free atomic-counter hot path + shared
1Hz sampler thread + cheap concurrent reads via small mutex.
includes the subtle bits: memory ordering choice, ring sizing,
saturating sub, init-zero detection, and the backoff-reset
bug that's invisible until you've been running for hours.

learned during logfire-zig v0.2.0 work: file-path test discovery
(_ = @import('foo.zig')) only descends into files in the same build
module as the test root. when build.zig declares another module via
b.createModule, you can't reach its files via file-path import — zig
errors with 'file exists in modules X and root'.

fix: a separate addTest target rooted at the other module's source
file, depended from the test step. example from logfire-zig/build.zig
included.

new files:
- languages/ziglang/0.16/logging.md: how std.log + std.options.logFn
work, why direct-emit library APIs are an anti-pattern, severity
mapping into OTEL
- observability/logfire-clients.md: the universal pipeline shape
(LoggerProvider → BatchLogProcessor → OTLP exporter), how each
language client adapts its standard logging facade as a bridge,
what otel-zig already provides, what logfire-zig is missing

derived from reading pydantic/logfire (python), pydantic/logfire-rust,
otel-zig/src/sdk/logs, and zig stdlib lib/std/log.zig.

testing.md: zig build test silently runs zero tests when blocks live
in non-root modules and only re-exports point at them. document the
test { _ = @import(...) } pattern, the verify-by-deliberate-failure
trick, and --summary all for spotting zero-discovery regressions.

comptime.md: string-type detection for anytype adapters (literals
and @tagName return *const [N:0]u8, not []const u8) and the
comptime-sql escape hatch — when adopting an external library that
builds sql at runtime, you need a parallel runtime path; don't try
to stringify through the comptime api.

both come out of leaflet-search adopting zug as a sqlite migration
runner: the test-discovery rule had been silently skipping ~5 test
blocks for months, and the @tagName type bit me when testing an
anytype adapter with pre-coerced []const u8 args.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Split single pydantic.md into pydantic/ with:
- README.md — core idea, when to use what
- settings.md — BaseSettings, nested config, splitting by concern
- validation.md — Annotated types as reusable type library (from prefect/types/)
- serialization.md — model_dump, JSON round-trips, TypeAdapter

Preps for plyr.fm config.py decomposition (phase 3).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>