docs: comprehensive documentation for developers and AI agents

[thorwhalen]

Summary

This PR adds a comprehensive set of documentation files for the dol package, targeting two audiences: developers exploring dol's design and AI coding agents working on or with dol.

---

New Files

misc/docs/ — Design & Analysis Documents

File	Contents
general_design.md	Language-agnostic design principles: DOL as middleware, the KV interface, the 4-transform pipeline, layered composition ("Russian dolls"), multi-store patterns
python_design.md	Python architecture deep dive: class hierarchy (Collection → KvReader → KvPersister → Store), wrap_kvs full parameter reference, store_decorator 4-way usage, Codec/Sig/Pipe patterns, constructive critique
issues_and_discussions.md	Thematic analysis of 30+ GitHub issues and 20+ discussions, organized into 10 categories: wrap_kvs tensions, codec ecosystem, key transforms, caching/performance, context managers, composite stores, batching, interface extension, docs, cross-platform
frontend_dol_ideas.md	Full architecture design for zoddal (ZOD-Data-Access-Layer) — a TypeScript analog to dol. Includes KvStore<K,V> interface, wrapKvs(), ValueCodec/KeyCodec types, built-in adapters (in-memory, REST, IndexedDB), and bridge to DataProvider
generate_llms_txt_instruction.md	Instructions for generating llms.txt / llms-full.txt files

Root-Level Files

File	Contents
llms.txt	llmstxt.org format overview — H1, blockquote summary, key concepts, Core API links, examples, optional links
llms-full.txt	Full API reference per module (dol.base, dol.trans, dol.kv_codecs, dol.filesys, dol.caching, dol.paths, dol.sources, dol.signatures, dol.util) with signatures, docstrings, and runnable examples
CLAUDE.md	AI agent guide: key files table, core patterns, 3 ways to create stores, ready-made codecs, store decorators, caching, testing approach, docs index, known limitations/gotchas

.claude/ — AI Agent Resources

File	Contents
.claude/rules/dol-conventions.md	Coding conventions: KvReader/KvPersister base classes, wrap_kvs best practices, X_of_Y naming, codec patterns, testing, no silent failures
.claude/commands/new-store.md	/new-store slash command — guides agent to create a new store with backend, key/value transforms, docstring and doctest
.claude/commands/explain-store.md	/explain-store slash command — traces MRO, wrap_kvs layers, and draws read/write pipeline
.claude/commands/add-codec.md	/add-codec slash command — implements a ValueCodec/KeyCodec pair with composition example

---

Key Background Findings

Architecture Agent Output

The background codebase exploration confirmed:

• 41 files, pure Python, zero external deps
• trans.py is the largest/most complex module (~2100 lines) — wrap_kvs at line 1802 is the central function
• Key idioms: DelegatedAttribute descriptor, redirect_getattr_to_getitem, lazyprop, double_up_as_factory
• dig.py (tracing/introspection) and appendable.py are secondary but notable modules not yet prominent in public docs

GitHub Issues Agent Output

Confirmed 10 architectural pain points, with specific issues:

• Issue wrap_kvs inconsistencies (due to incorrect signature-based conditioning) #9 — wrap_kvs signature-inspection magic causes silent failures (e.g., bytes.decode unbound fails, lambda x: x.decode() works)
• Issue wrap_kvs will wrap the instance but self of instance is not wrapped #18 — self inside wrap_kvs-decorated class methods is unwrapped, causing transform inconsistencies
• Issue Store.wrap breaks the signature of subclasses. #6 — @Store.wrap breaks subclass __init__ signatures
• Issue Making conditional_data_trans better, and generally; recursively applying wrappers #10 — Recursive wrapper application needed for nested stores
• Issue Enabling (optional) KeyPath ability to write when path doesn't already exist #16 — KeyPath needs defaultdict-like auto-creation for nested writes
• Issues Make dol tests windows compatible #52, Make dol tests work on windows. #58 — Windows path compatibility (CI failures)
• Issue Fast update and synching #56 — store.update(src) is O(n) with no coordination between source/target for efficient sync

---

Total

~2,800 lines across 12 new files.