Add various doc updates

They are still very far from complete.

docs/freedom-hacking-and-responsibility.md

@@ -0,0 +1,142 @@
+# Freedom, Hacking, and Responsibility
+
+This framework is **free and open source software**.
+
+That fact is not incidental. It is a deliberate ethical, practical, and technical choice.
+
+This document explains how freedom to modify coexists with strong guidance about *how the framework is meant to be used* — without contradiction, and without apology.
+
+---
+
+## The short version
+
+* This is free software. You are free to modify it.
+* The framework has documented invariants for good reasons.
+* You are encouraged to explore, question, and patch.
+* You are discouraged from casually undermining guarantees you still expect to rely on.
+* Clarity beats enforcement.
+
+Freedom with understanding beats both lock-in and chaos.
+
+
+---
+
+## Your Freedom
+
+You are free to:
+
+* study the source code
+* run the software for any purpose
+* modify it in any way
+* fork it
+* redistribute it, with or without changes
+* submit patches, extensions, or experiments
+
+…subject only to the terms of the license.
+
+These freedoms are foundational. They are not granted reluctantly, and they are not symbolic. They exist so that:
+
+* you can understand what your software is really doing
+* you are not trapped by vendor control
+* the system can outlive its original authors
+
+---
+
+## Freedom Is Not the Same as Endorsement
+
+While you are free to change anything, **not all changes are equally wise**.
+
+Some parts of the framework are carefully constrained because they encode:
+
+* security assumptions
+* lifecycle invariants
+* hard-won lessons from real systems under stress
+
+You are free to violate these constraints in your own fork.
+
+But the framework’s documentation will often say things like:
+
+* “do not modify this”
+* “application code must not depend on this”
+* “this table or class is framework-owned”
+
+These statements are **technical guidance**, not legal restrictions.
+
+They exist to answer the question:
+
+> *If you want this system to remain upgradeable, predictable, and boring — what should you leave alone?*
+
+---
+
+## The Intended Social Contract
+
+The framework makes a clear offer:
+
+* We expose our internals so you can learn.
+* We provide explicit extension points so you can adapt.
+* We document invariants so you don’t have to rediscover them the hard way.
+
+In return, we ask that:
+
+* application code respects documented boundaries
+* extensions use explicit seams rather than hidden hooks
+* patches that change invariants are proposed consciously, not accidentally
+
+Nothing here is enforced by technical locks.
+
+It is enforced — insofar as it is enforced at all — by clarity and shared expectations.
+
+---
+
+## Hacking Is Welcome
+
+Exploration is not just allowed; it is encouraged.
+
+Good reasons to hack on the framework include:
+
+* understanding how it works
+* evaluating whether its constraints make sense
+* adapting it to unfamiliar environments
+* testing alternative designs
+* discovering better abstractions
+
+Fork it. Instrument it. Break it. Learn from it.
+
+Many of the framework’s constraints exist *because* someone once ignored them and paid the price.
+
+---
+
+## Patches, Not Patches-in-Place
+
+If you discover a problem or a better design:
+
+* patches are welcome
+* discussions are welcome
+* disagreements are welcome
+
+What is discouraged is **quietly patching around framework invariants inside application code**.
+
+That approach:
+
+* obscures intent
+* creates one-off local truths
+* makes systems harder to reason about
+
+If the framework is wrong, it should be corrected *at the framework level*, or consciously forked.
+
+---
+
+## Why This Is Not a Contradiction
+
+Strong opinions and free software are not enemies.
+
+Freedom means you can change the software.
+
+Responsibility means understanding what you are changing, and why.
+
+A system that pretends every modification is equally safe is dishonest.
+
+A system that hides its internals to prevent modification is hostile.
+
+This framework aims for neither.
+