docs: add AGENTS.md and mark deprecated APIs for cleanup

AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS
+
+## Overview
+
+This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks.
+
+The main modules include:
+
+- `BTreeMap` — key-value storage
+- `BTreeSet` — sets
+- `Vec` — growable arrays
+- `Cell` — single values
+- `Log` — append-only data
+- `MinHeap` — priority queues
+- `MemoryManager` — coordinates multiple structures in stable memory
+
+## Index
+
+Key entry points for understanding and using this library:
+
+- `README.md` — quick start and basic usage patterns
+- `docs/` — mdBook with concepts, design principles, and tutorials
+- `src/lib.rs` — crate-level documentation and public API overview
+- `examples/` — production-ready examples showing real-world usage
+- `src/btreemap.rs`, `src/btreeset.rs`, `src/vec.rs`, etc. — individual module documentation
+- `Cargo.toml` — version and dependency information
+
+## Source of truth
+
+Code defines behavior. Documentation must accurately reflect the current implementation. When making changes:
+
+- update documentation in the same PR as code changes
+- ensure examples compile and run correctly
+- keep API documentation synchronized with function signatures
+- update book chapters when changing core concepts
+
+## Reading path
+
+Follow this sequence to understand the library:
+
+1. `README.md` for overview and quick examples
+1. `docs/src/introduction/` for concepts and design principles
+1. `docs/src/concepts/` for `Memory` trait and `MemoryManager` details
+1. module documentation (`src/*.rs`) for specific data structure APIs
+1. `examples/` for production usage patterns
+1. code comments for implementation details
+
+## Checklist
+
+When changing public APIs:
+
+- describe scope of changes in PR description
+- update module-level documentation for affected types
+- add or update runnable examples demonstrating the change
+- update book chapters if concepts change
+- verify `cargo doc` builds without warnings
+- verify `mdbook build` succeeds
+- test examples compile and run
+
+## Quality bar
+
+Every public type and module must have:
+
+- short overview explaining purpose and use cases
+- basic usage example that compiles
+- links to related documentation or examples
+- clear parameter and return value descriptions
+- complexity information where relevant
+- error conditions and panics documented

src/btreemap.rs

@@ -699,12 +699,16 @@ where
 
     /// Removes all elements from the map.
     #[deprecated(since = "0.6.3", note = "please use `clear_new` instead")]
+    // TODO: In next major release (v1.0), remove this deprecated method and rename
+    // `clear_new` to `clear` for consistency with standard Rust collections.
     pub fn clear(self) -> Self {
         let mem = self.allocator.into_memory();
         Self::new(mem)
     }
 
     /// Removes all elements from the map.
+    // TODO: In next major release (v1.0), rename this method to `clear` to follow
+    // standard Rust collection naming conventions.
     pub fn clear_new(&mut self) {
         self.root_addr = NULL;
         self.length = 0;
@@ -1212,6 +1216,7 @@ where
     /// The new name, `iter_from_prev_key`, better reflects this behavior and
     /// improves code clarity.
     #[deprecated(note = "use `iter_from_prev_key` instead")]
+    // TODO: In next major release (v1.0), remove this deprecated method to clean up the API.
     pub fn iter_upper_bound(&self, bound: &K) -> Iter<'_, K, V, M> {
         self.iter_from_prev_key(bound)
     }

src/memory_manager.rs

@@ -126,6 +126,13 @@ const HEADER_RESERVED_BYTES: usize = 32;
 /// -------------------------------------------------- <- Page ((MAX_NUM_BUCKETS - 1) * N + 1)
 /// Bucket MAX_NUM_BUCKETS                ↕ N pages
 /// ```
+///
+/// # Current Limitations and Future Improvements
+///
+/// - Buckets are never deallocated once assigned to a memory ID, even when the memory becomes empty
+/// - Clearing data structures (BTreeMap, Vec) does not reclaim underlying bucket allocations
+/// - Long-running canisters may accumulate unused buckets, increasing storage costs
+/// - Future versions may consider automatic bucket reclamation and memory compaction features
 pub struct MemoryManager<M: Memory> {
     inner: Rc<RefCell<MemoryManagerInner<M>>>,
 }