Update README , add indices.md, remove CLAUDE.md

Author: codeboost

CLAUDE.md

@@ -1,3 +1,17 @@
+> **⚠️ Alpha Software - Work in Progress**
+>
+> This project is in early development and rapidly evolving. 
+> Expect breaking changes, rough edges, and incomplete documentation.
+>
+> **🤝 Help Wanted!** If you find this useful, please consider contributing:
+> - Report bugs and issues you encounter
+> - Suggest improvements or new features
+> - Submit pull requests for fixes or enhancements
+> - Share your configuration patterns and workflows
+> - Help improve documentation and examples
+>
+> Your feedback and contributions will help make this tool better for the entire Clojure community!
+
 ## Overview
 
 `xitdb-clj` is a database for efficiently storing and retrieving immutable, persistent data structures. 
@@ -7,10 +21,6 @@ itself a port of [xitdb](https://github.com/radarroark/xitdb), written in Zig.
 
 `xitdb-clj` provides atom-like semantics when working with the database from Clojure.
 
-### Experimental
-
-Code is still in early stages of 'alpha', things might change or break in future versions.
-
 ## Main characteristics
 
 - Embeddable, tiny library.
@@ -61,6 +71,27 @@ For the programmer, a `xitdb` database behaves exactly like a Clojure atom.
 (get-in @db [:users "alice" :age])
 ;; => 31
 ```
+One important distinction to the Clojure atom is that inside a transaction (eg. a `swap!`), 
+'change' operations on the received db argument are mutating it.
+
+```clojure
+(with-db [db (xdb/xit-db :memory)]
+  (reset! db {})
+  (swap! db (fn [db]
+              (let [db1 (assoc db :foo :bar)]
+                (println "db1:" db1)
+                (println "db:" db)))))
+```
+prints 
+```
+db1: {:foo :bar}
+db: {:foo :bar}
+```
+As you can see, `(assoc db :foo :bar)` changed the value of `db`, in contrast
+to how it works with a Clojure persistent map. This is because, inside `swap!`, 
+`db` is referencing a WriteCursor, which writes the value to the underlying 
+ArrayList or HashMap objects inside `xit-db-java`.
+The value will actually be commited to the database when the `swap!` function returns.
 
 ## Data structures are read lazily from the database
 

README.md

@@ -0,0 +1,43 @@
+# Using indices with xitdb
+
+There's no built-in support for indices, because... 
+Indices are yet another data structure which you can store in the database.
+
+```clojure 
+
+(defn records->index-set
+  "Returns a map keyed by `k` and valued by a `set` of ids."
+  [records k & {:keys [id] :or {id :id}}]
+  (->> records
+       (group-by k)
+       (map (fn [[k songs]]
+              [k (->> songs (map id) set)]))
+       (into {})))
+
+(defn update-index
+  "Updates an index in `m`.
+  All indices are stored in the 'index' map (eg. songs-index).
+  Eg:
+  `{:songs-index {:artist {'foo' #{8 9}}}`
+  The songs-index contains an index which groups the songs by artist name -> set of song ids.
+  k represents the `key` on which the `records` are going to be grouped and
+  then merged into the `k` index."
+  [m index k records]
+  (let [k->song-id-set (records->index-set records k)]
+    (update-in m [index k] #(merge-with into % k->song-id-set))))
+
+(defn insert-songs! [db songs]
+  (let [id->song (into {} (map (juxt :id identity)) songs)]
+    (swap! db (fn [m]
+                (-> m
+                    (update :songs merge id->song)
+                    (update-index :songs-indices :artist songs)
+                    (update-index :songs-indices :tag songs)
+                    (update-index :songs-indices :year songs))))))
+```
+
+
+# External indices
+Indices can be stored in a separate database file. 
+In fact, you might not need all indices in your 'live' database, but you might 
+need some indices for analytics or reporting.