diff --git a/docs/plan-expanded.md b/docs/archive/plan-expanded.md
similarity index 95%
rename from docs/plan-expanded.md
rename to docs/archive/plan-expanded.md
index cb6911c..25d7d32 100644
--- a/docs/plan-expanded.md
+++ b/docs/archive/plan-expanded.md
@@ -1,3 +1,7 @@
+# archived: expanded plan (partially implemented)
+
+This file is preserved for context/history. Current direction lives in `docs/roadmap.md`.
+
 # zat - expanded scope
 
 the initial release delivered string primitives (Tid, Did, Handle, Nsid, Rkey, AtUri). this plan expands toward a usable AT Protocol sdk.
diff --git a/docs/plan-initial.md b/docs/archive/plan-initial.md
similarity index 97%
rename from docs/plan-initial.md
rename to docs/archive/plan-initial.md
index 12d8f62..6baa794 100644
--- a/docs/plan-initial.md
+++ b/docs/archive/plan-initial.md
@@ -1,3 +1,7 @@
+# archived: initial plan (out of date)
+
+This file is preserved for context/history. Current direction lives in `docs/roadmap.md`.
+
 # zat - zig atproto primitives
 
 low-level building blocks for atproto applications in zig. not a full sdk - just the pieces that everyone reimplements.
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 0000000..e680a27
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,40 @@
+# roadmap
+
+`zat` is a grab bag of **AT Protocol building blocks** in Zig: parsers, validators, resolvers, and small protocol helpers.
+
+This roadmap is intentionally short. If it doesn’t fit into one file, it probably belongs in issues.
+
+## now
+
+- keep current APIs stable (0.x semver)
+- tighten docs/examples as real apps discover sharp edges
+- keep the “primitives, not framework” ethos
+
+## next
+
+### polish
+
+- improve docs around common workflows:
+  - resolving handle → DID → PDS
+  - making XRPC calls + parsing JSON
+  - verifying JWTs from DID documents
+- add more integration tests that hit real-world edge cases (without becoming flaky)
+
+### primitives
+
+- fill gaps that show up repeatedly in other atproto projects:
+  - CIDs and common multiformats plumbing
+  - richer `AtUri` helpers (safe joins, parsing variants)
+  - more ergonomic JSON navigation patterns (still optional, no forced codegen)
+
+## later (maybe)
+
+- lexicon codegen is still “probably a separate project”
+- higher-level clients/frameworks stay out of scope
+
+## non-goals
+
+- token refresh/session frameworks
+- opinionated app scaffolding
+- “one true SDK” that tries to do everything
+
diff --git a/scripts/build-wisp-docs.mjs b/scripts/build-wisp-docs.mjs
index 3b65cd6..1c7972f 100644
--- a/scripts/build-wisp-docs.mjs
+++ b/scripts/build-wisp-docs.mjs
@@ -139,6 +139,8 @@ async function main() {
 
   const mdFiles = (await exists(docsDir)) ? await listMarkdownFiles(docsDir) : [];
 
+  // Copy all markdown under docs/ (including archives), but only include non-archive
+  // paths in the sidebar manifest.
   for (const rel of mdFiles) {
     const src = path.join(docsDir, rel);
     const dst = path.join(outDocsDir, rel);
@@ -146,9 +148,25 @@ async function main() {
     await cp(src, dst);
 
     const md = await readFile(src, "utf8");
-    pages.push({ path: rel, title: normalizeTitle(titleFromMarkdown(md, rel)) });
+    if (!rel.startsWith("archive/")) {
+      pages.push({ path: rel, title: normalizeTitle(titleFromMarkdown(md, rel)) });
+    }
   }
 
+  // Stable nav order: README homepage, then roadmap, then changelog, then the rest.
+  pages.sort((a, b) => {
+    const order = (p) => {
+      if (p === "index.md") return 0;
+      if (p === "roadmap.md") return 1;
+      if (p === "changelog.md") return 2;
+      return 3;
+    };
+    const ao = order(a.path);
+    const bo = order(b.path);
+    if (ao !== bo) return ao - bo;
+    return a.title.localeCompare(b.title);
+  });
+
   await writeFile(
     path.join(outDir, "manifest.json"),
     JSON.stringify({ pages }, null, 2) + "\n",