ProjectASAP · zzylol · Aug 23, 2026 · Aug 23, 2026
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ cargo build
 cargo test --workspace
 ```
 
-No external setup required. See [`docs/user-guide.md`](docs/user-guide.md) for how to run a
+No external setup required. See [`docs/user-guide/user-guide.md`](docs/user-guide/user-guide.md) for how to run a
 query through the pipeline.
 
 ## Glossary
@@ -220,17 +220,17 @@ semantic information that matters downstream.
 
 - Change input from a single query string to `QueryWorkload` (tracked in [#194](https://github.com/ProjectASAP/ASAPPlanner/issues/194)
 - Remove legacy data structures and types (tracked in [#179](https://github.com/ProjectASAP/ASAPPlanner/issues/179), [#205](https://github.com/ProjectASAP/ASAPPlanner/issues/205)
-- Implement the ASAP-aware mapping [logic and interfaces](docs/asap_aware_mapping.md)
+- Implement the ASAP-aware mapping [logic and interfaces](docs/design_docs/asap_aware_mapping.md)
 - Connect output of ASAPPlanner to asap-fusion
 - Connect output of ASAPPlanner to ASAPCollector and ASAPQuery (see open question #1 below)
 
 # Next steps
 
-- [Description of pre-ASAP IR](docs/pre-asap-ir.md)
-- [Description of post-ASAP IR](docs/post-asap-ir.md)
-- [Converting a QueryWorkload to a pre-ASAP plan](docs/parse_and_canonicalize.md)
-- [Converting a pre-ASAP plan to a post-ASAP plan](docs/asap_aware_mapping.md)
-- [Guide on how to use ASAPPlanner](docs/user-guide.md)
+- [Description of pre-ASAP IR](docs/design_docs/pre-asap-ir.md)
+- [Description of post-ASAP IR](docs/design_docs/post-asap-ir.md)
+- [Converting a QueryWorkload to a pre-ASAP plan](docs/design_docs/parse_and_canonicalize.md)
+- [Converting a pre-ASAP plan to a post-ASAP plan](docs/design_docs/asap_aware_mapping.md)
+- [Guide on how to use ASAPPlanner](docs/user-guide/user-guide.md)
 
 # Open questions
 

diff --git a/crates/asap-aware-mapping/src/bind.rs b/crates/asap-aware-mapping/src/bind.rs
@@ -115,7 +115,7 @@ pub fn implement_tree_with(
 /// A first pass over `roots` counts each distinct `Rc<QueryExpr>` pointer's
 /// true `consumer_count` across the whole workload, so the
 /// [`CseCandidate`]/[`CostModel::cse_share_decision`] cost comparison (see
-/// `docs/cse-cost-model-decision.md`) sees the real total, not a running
+/// `docs/design_docs/cse-cost-model-decision.md`) sees the real total, not a running
 /// count that grows as roots are processed left to right. The decision is
 /// made once, the first time a shared pointer is bound, and cached alongside
 /// the bound `SummaryNode` so every later occurrence of that same `Rc`

diff --git a/crates/asap-aware-mapping/src/cost_model.rs b/crates/asap-aware-mapping/src/cost_model.rs
@@ -39,7 +39,7 @@
 //! ([`asap_types::pre_asap::cse::share_common_subtrees`], issue #223 stages
 //! 1-2, PR #235) is actually worth sharing, via a real Volcano/Cascades-style
 //! cost comparison rather than a fixed rule. See
-//! `docs/cse-cost-model-decision.md` for the full design discussion (why
+//! `docs/design_docs/cse-cost-model-decision.md` for the full design discussion (why
 //! cost-based, why not a full plan-search engine, the layering constraint
 //! that forces detection to stay cost-agnostic). [`bind::implement_workload_with`](crate::bind::implement_workload_with)
 //! is the caller.
@@ -59,7 +59,7 @@ use crate::boundary::Implementation;
 /// the first time it binds a subtree that
 /// [`asap_types::pre_asap::cse::share_common_subtrees`] already collapsed
 /// onto one `Rc` for two or more workload roots. See
-/// `docs/cse-cost-model-decision.md`.
+/// `docs/design_docs/cse-cost-model-decision.md`.
 pub struct CseCandidate<'a> {
     /// The shared pre-ASAP subtree itself.
     pub subtree: &'a QueryExpr,
@@ -211,7 +211,7 @@ pub trait CostModel {
     /// Estimate the one-time cost of recomputing `candidate.subtree`
     /// independently at a single use site. Default:
     /// [`default_cse_recompute_cost`] (a structural-size proxy). See
-    /// `docs/cse-cost-model-decision.md`.
+    /// `docs/design_docs/cse-cost-model-decision.md`.
     fn cse_recompute_cost(&self, candidate: &CseCandidate) -> f64 {
         default_cse_recompute_cost(candidate.subtree)
     }
@@ -223,7 +223,7 @@ pub trait CostModel {
     /// `candidate.bound_summary`'s output schema actually carries summary
     /// state (falls back to the cheapest, `Plain`, weight if none does —
     /// e.g. `bound_summary` is a passthrough `Logical` node with nothing
-    /// summary-shaped to maintain). See `docs/cse-cost-model-decision.md`.
+    /// summary-shaped to maintain). See `docs/design_docs/cse-cost-model-decision.md`.
     fn cse_shared_maintenance_cost(&self, candidate: &CseCandidate) -> f64 {
         let family = candidate
             .bound_summary
@@ -242,7 +242,7 @@ pub trait CostModel {
     /// Decide whether to reuse one shared `SummaryNode` across every
     /// consumer of `candidate`, or bind each occurrence independently — a
     /// Volcano/Cascades-style cost comparison (issue #237, #223 stage 4; see
-    /// `docs/cse-cost-model-decision.md`): share iff the estimated cost of
+    /// `docs/design_docs/cse-cost-model-decision.md`): share iff the estimated cost of
     /// maintaining one shared summary is no greater than the estimated total
     /// cost of recomputing it independently everywhere it's used.
     ///

diff --git a/crates/types/src/pre_asap/cse.rs b/crates/types/src/pre_asap/cse.rs
@@ -4,7 +4,7 @@
 //!
 //! CSE only runs on an already-bound, already-canonicalized tree —
 //! structural matching is meaningless before canonicalization has converged
-//! semantically-equivalent queries onto one shape (`docs/pre-asap-ir.md`
+//! semantically-equivalent queries onto one shape (`docs/design_docs/pre-asap-ir.md`
 //! design principle 3; `median(latency)` and `approx_percentile_cont(latency,
 //! 0.5)` already lower to an identical `AggIntent::Quantile` today, per
 //! `sql_lowering.rs`'s `median_is_the_same_intent_as_an_explicit_half_percentile`
@@ -94,7 +94,7 @@
 //! `asap_aware_mapping::cost_model::CostModel::cse_share_decision` and its
 //! caller, `asap_aware_mapping::bind::implement_workload_with` — a real,
 //! Volcano/Cascades-style cost comparison over what this module detects, not
-//! a fixed rule. See `docs/cse-cost-model-decision.md`. This module's own
+//! a fixed rule. See `docs/design_docs/cse-cost-model-decision.md`. This module's own
 //! unconditional "share whenever legal" behavior is unchanged: detection
 //! stays cost-agnostic by construction (this crate cannot depend on
 //! `asap-aware-mapping`'s `CostModel`), and the cost-aware decision is

diff --git a/docs/asap_aware_mapping.md → docs/design_docs/asap_aware_mapping.md b/docs/asap_aware_mapping.md → docs/design_docs/asap_aware_mapping.md
diff --git a/docs/cse-cost-model-decision.md → docs/design_docs/cse-cost-model-decision.md b/docs/cse-cost-model-decision.md → docs/design_docs/cse-cost-model-decision.md
diff --git a/docs/parse_and_canonicalize.md → docs/design_docs/parse_and_canonicalize.md b/docs/parse_and_canonicalize.md → docs/design_docs/parse_and_canonicalize.md
diff --git a/docs/post-asap-ir.md → docs/design_docs/post-asap-ir.md b/docs/post-asap-ir.md → docs/design_docs/post-asap-ir.md
diff --git a/docs/pre-asap-ir.md → docs/design_docs/pre-asap-ir.md b/docs/pre-asap-ir.md → docs/design_docs/pre-asap-ir.md
diff --git a/docs/user-guide.md → docs/user-guide/user-guide.md b/docs/user-guide.md → docs/user-guide/user-guide.md
@@ -116,6 +116,6 @@ Match on `post_asap.expr` (a `SummaryExpr`):
 - `SummaryEstimate { summary_input, query }` — wraps a sketch `SummaryAgg`; `query` is what to
   read out of it (`Quantile`, `Cardinality`, `TopK`, `PointCount`).
 
-`docs/asap_aware_mapping.md` has the conceptual background (why this layer exists, what an
-"implementation" is); `docs/pre-asap-ir.md` / `docs/post-asap-ir.md` are the node-by-node IR
+`docs/design_docs/asap_aware_mapping.md` has the conceptual background (why this layer exists, what an
+"implementation" is); `docs/design_docs/pre-asap-ir.md` / `docs/design_docs/post-asap-ir.md` are the node-by-node IR
 reference.