docs: mark stale docs/dev/ design notes as outdated

AGENTS.md

@@ -43,9 +43,21 @@ uv run mypy .                         # Type check
 | `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`) |
 | `test/` | All tests (run from repo root) |
 | `docs/examples/` | Example code (run as tests via pytest) |
+| `docs/dev/` | Internal design notes — **not verified documentation** |
 | `.agents/skills/` | Agent skills ([agentskills.io](https://agentskills.io) standard) |
 | `scratchpad/` | Experiments (git-ignored) |
 
+⚠️ **`docs/dev/` is informal design notes, not maintained documentation.** Some
+notes are current, some describe proposals that were never implemented or APIs
+that have since changed, and some are unfinished stubs — nothing in the
+directory is guaranteed accurate. Before relying on a claim from `docs/dev/` in
+code, docs, or a review comment: check the top of the file for a status banner
+(`outdated` / `unfinished stub` / `informal brainstorm`), and independently
+verify the specific claim (class, method, signature, path) against current
+source rather than trusting the note. See
+[#1482](https://github.com/generative-computing/mellea/issues/1482) for the
+ongoing discussion on a long-term currency policy for this directory.
+
 ## 3. Test Markers
 Tests use a four-tier granularity system (`unit`, `integration`, `e2e`, `qualitative`) plus backend and resource markers. The `unit` marker is auto-applied by conftest — never write it explicitly. The `llm` marker is deprecated; use `e2e` instead.
 

docs/dev/constrained_decoding.md

@@ -1,5 +1,10 @@
 # Constrained Decoding
 
+> **Status: informal brainstorm.** This note records open questions and
+> informally paraphrased suggestions from an early discussion; no decision was
+> ever recorded and nothing below should be treated as settled design. See
+> #1482 for the `docs/dev/` currency discussion.
+
 ## How do constraints get defined?
 
 Should we be thinking bigger than pydantic? Should it be possible to pass arbitrary grammars? If so, what's the abstract interface for those? Should this be factored out into llm-io?

docs/dev/intrinsics_and_adapters.md

@@ -1,4 +1,11 @@
 # Intrinsics and Adapters
+
+> **Status: outdated.** "Mellea currently only supports IntrinsicAdapters and
+> Intrinsics" predates Epic #929's capability-based `Identity` / `_find_adapter`
+> adapter model (see [`requirement_aLoRA_rerouting.md`](requirement_aLoRA_rerouting.md)
+> for the current lookup mechanism). A rewrite of this note is tracked in
+> #1144. See #1482 for the broader `docs/dev/` currency discussion.
+
 Note: Mellea currently only supports IntrinsicAdapters and Intrinsics.
 
 ## Basics

docs/dev/mellea_library.md

@@ -1,5 +1,9 @@
 # Mellea should be as close to a library as possible
 
+> **Note.** This is a design-philosophy statement (library vs. framework), not
+> an API reference, and it has not been re-verified line-by-line against the
+> current codebase. See #1482 for the `docs/dev/` currency discussion.
+
 We should make it possible to use mellea as a library (as opposed to a framework).
 
 In the context of LLM applications, the library vs framework distinction really boils down to how you treat the backend.

docs/dev/mify.md

@@ -1,5 +1,15 @@
 # mify
 
+> **Status: outdated.** The code below does not run as written — `Circle` has no
+> `__init__`, `Customer.__init__` is missing its `self` parameter, and the
+> second example calls `mify(c)` / `m.query(c, ...)` on an undefined `c` (it
+> meant `customer`) — and the implementation link points to
+> `mellea/stdlib/mify.py`, which has moved to
+> `mellea/stdlib/components/mify.py`. For accurate, working coverage of this
+> topic, see [`docs/docs/concepts/mobjects-and-mify.md`](../docs/concepts/mobjects-and-mify.md)
+> (published) or [`docs/examples/mify/mify.py`](../examples/mify/mify.py). See
+> #1482 for the `docs/dev/` currency discussion.
+
 In classical programming, object-orientation provides a way to couple data and functionality.
 Classes have fields and methods. Fields store data and methods operate over that data.
 
@@ -69,5 +79,5 @@ customer.execute("send an email.", email_body, email_subject)
 ```
 
 For more examples and information, see
-- [Mify Examples](../examples/mify.py)
-- [Mify Implementation](../../mellea/stdlib/mify.py)
+- [Mify Examples](../examples/mify/mify.py)
+- [Mify Implementation](../../mellea/stdlib/components/mify.py)

docs/dev/spans.md

@@ -1,5 +1,13 @@
 # Design Document for Spans
 
+> **Status: unfinished stub.** This note breaks off mid-decision ("We need to
+> document which approach we choose...") and no decision was ever recorded; no
+> `SpanContext` or `__span_repr__` exists in the codebase. The `/dev/spans` URL
+> on the published docs site now redirects to the unrelated OpenTelemetry
+> tracing page ([`docs/docs/observability/tracing.md`](../docs/observability/tracing.md)),
+> which does not cover this design. See #1482 for the `docs/dev/` currency
+> discussion.
+
 ## Span Contexts
 
 We will introduce a SpanContext which will behave kind of like a heap but with transformer-running-on-GPU memory primitives instead of malloc/realloc/free. The public interface to a SpanContext will roughly correspond to the sort of stuff you can do in Span algebras, if you've seen some of that work.

docs/dev/tool_calling.md

@@ -1,5 +1,11 @@
 # Tool Calling
 
+> **Status: outdated.** The `SessionToolCallingProtocol` / `MelleaSessionToolProtocol`
+> mixin proposed below (with `tool_call_result()` and `call_tool()`) was never
+> implemented. The linked example, `docs/examples/agents/react/react_from_scratch/react.py`,
+> uses its own `ReactTool` / `ReactToolbox` classes instead. See #1482 for the
+> `docs/dev/` currency discussion.
+
 ## Problem Statement
 
 Context management and execution of tool calls are inextricably linked, because most