diff --git a/DESIGN.md b/DESIGN.md
index 4e6dc049f3..a7a8a28451 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -2,9 +2,6 @@
 μpb Design
 ----------
 
-**NOTE:** the design described here is being implemented currently, but is not
-yet complete.  The repo is in heavy transition right now.
-
 μpb has the following design goals:
 
 - C89 compatible.
@@ -62,22 +59,14 @@ link μpb will never need to worry about this.
 TODO
 ----
 
-The current state of the repo is quite different than what is described above.
-Here are the major items that need to be implemented.
-
-1. implement the core generic protobuf binary encoder/decoder that uses a
-   `upb_msglayout*`.
-2. remove all mention of handlers, sink, etc. from core into their own module.
-   All of the handlers stuff needs substantial revision, but moving it out of
-   core is the first priority.
-3. move all of the def/refcounted stuff out of core.  The defs also need
-   substantial revision, but moving them out of core is the first priority.
-4. revise our generated code until it is in a state where we feel comfortable
-   committing to API/ABI stability for it.  This may involve moving different
-   parts of the generated code into separate files, like keeping the serialized
-   descriptor in a separate file from the compact msglayout.
-5. revise all of the existing encoders/decoders and handlers.  We probably
-   will want to keep handlers, since they let us decouple encoders/decoders
-   from `upb_msg`, but we need to simplify all of that a LOT.  Likely we will
-   want to make handlers only per-message instead of per-field, except for
-   variable-length fields.
+1. revise our generated code until it is in a state where we feel comfortable
+   committing to API/ABI stability for it.  In particular there is an open
+   question of whether non-ABI-compatible field accesses should have a
+   fastpath different from the ABI-compatible field access.
+1. Add missing features (maps, extensions, unknown fields).
+1. Flesh out C++ wrappers.
+1. *(lower-priority)*: revise all of the existing encoders/decoders and
+   handlers.  We probably will want to keep handlers, since they let us decouple
+   encoders/decoders from `upb_msg`, but we need to simplify all of that a LOT.
+   Likely we will want to make handlers only per-message instead of per-field,
+   except for variable-length fields.
diff --git a/README.md b/README.md
index 6edb2454b9..feaa4d5295 100644
--- a/README.md
+++ b/README.md
@@ -10,16 +10,16 @@
 
 upb generates a C API for creating, parsing, and serializing messages
 as declared in `.proto` files.  upb is heavily arena-based -- all
-messages always live in an arena.  You control where the arena gets
-memory from, so the arena can come from stack memory, for example.
-Here is a simple example (`ConformanceRequest` and `ConformanceResponse`
-are generated message types):
+messages always live in an arena (note: the arena can live in stack or
+static memory if desired).  Here is a simple example:
 
 ```c
 #include "conformance/conformance.upb.h"
 
 void foo(const char* data, size_t size) {
   upb_arena *arena;
+
+  /* Generated message type. */
   conformance_ConformanceRequest *request;
   conformance_ConformanceResponse *response;
 
@@ -46,16 +46,11 @@ void foo(const char* data, size_t size) {
     }
   }
 
+  /* Frees all messages on the arena. */
   upb_arena_free(arena);
 }
 ```
 
-Messages are opaque, so you always have to use generated getter/setter
-methods to read/write fields.  This is somewhat unfortunate for C
-because the function names are long, but this is necessary to provide
-correct semantics for oneof fields, proto2 presence, etc.  It is also
-necessary for providing a stable ABI, in cases where that is desired.
-
 API and ABI are both subject to change!  Please do not distribute
 as a shared library for this reason (for now at least).