diff --git a/AGENTS.md b/AGENTS.md
index fa606d778..d9f03a952 100644
--- a/AGENTS.md
+++ b/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.
 
diff --git a/docs/dev/constrained_decoding.md b/docs/dev/constrained_decoding.md
index 4318443ef..8cc0b8e4a 100644
--- a/docs/dev/constrained_decoding.md
+++ b/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?
diff --git a/docs/dev/intrinsics_and_adapters.md b/docs/dev/intrinsics_and_adapters.md
index 3d1375921..40caa7fc7 100644
--- a/docs/dev/intrinsics_and_adapters.md
+++ b/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
diff --git a/docs/dev/mellea_library.md b/docs/dev/mellea_library.md
index 3baf14898..7b476dd09 100644
--- a/docs/dev/mellea_library.md
+++ b/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.
diff --git a/docs/dev/mify.md b/docs/dev/mify.md
index ab3af6e94..40f437a57 100644
--- a/docs/dev/mify.md
+++ b/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)
diff --git a/docs/dev/spans.md b/docs/dev/spans.md
index 28c19d3b9..6ea09946b 100644
--- a/docs/dev/spans.md
+++ b/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.
diff --git a/docs/dev/tool_calling.md b/docs/dev/tool_calling.md
index fff491d94..8a42bcbf2 100644
--- a/docs/dev/tool_calling.md
+++ b/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