From 4d7842a0e7b856beaa6e9d9471ba3182779d1ba8 Mon Sep 17 00:00:00 2001
From: ·𐑑𐑴𐑕𐑑𐑩𐑤
Date: Wed, 10 Dec 2025 13:00:26 +0000
Subject: further README updates

---
 README.rst         | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 lib/lock_loader.ml |   2 +-
 lib/lockfile.ml    |   2 +-
 lib/manifest.ml    |   2 +-
 4 files changed, 105 insertions(+), 4 deletions(-)

diff --git a/README.rst b/README.rst
index 4ec9016..e79b7b3 100644
--- a/README.rst
+++ b/README.rst
@@ -8,6 +8,7 @@ Fulfilling input pinning for Nix (& hopefully more)
 :author: toastal
 
 .. role:: ac
+.. role:: del
 .. role:: t
 
 Pronunciation
@@ -30,12 +31,18 @@ Nixtamal is a tool to pin input version like its predecessors :t:`niv`,
 :t:`npins`, :t:`Pinch`, :t:`Yae`\, & so on — as well as Nix’s experimental
 :t:`flakes`. Features include:
 
+• keeps a stable reference pin to supported :ac:`VCS`\s
 • supports mirrors for fetching [1]_
 • supports patch-based :ac:`VCS`\s, like Pijul & Darcs, in a first-class sense
   (tho ``nixpkgs`` will be required due to Nix ``builtins`` fetchers limitations)
 • uses a :ac:`KDL` manifest file with templating instead of :ac:`CLI` input
-  for inputs
 • supports arbitrary commands for getting the latest change
+  for inputs
+• refreshes inputs; skips frozen
+• locks new sources
+• supports arbitrary commands for getting the latest change which can be used
+  to avoid costly downloads/clones as well as for templating
+  for inputs
 • does not give any special privilege to any specific code forges
 • source code & community will never be hosted on a proprietary,
   privacy-invasive, megacorporate platform with obligations to shareholders or
@@ -45,10 +52,104 @@ Nixtamal is a tool to pin input version like its predecessors :t:`niv`,
 
 Future goals:
 
+• migrations from prior manifest × lockfile versions
+• migrations from Flakes, Npins, & Niv
+• more :ac:`VCS`\s
+• trying to get mirror support for :ac:`VCS`\s upstreamed into Nixpkgs
 • ``nixtamal heal`` for common pitfalls in ``manifest.kdl``
 • :ac:`TUI`?
 • provide a flake-like specification for project layout, but with less holes
 
+.. warning::
+
+	As this software is in the alpha stage, the maker reserves the right make
+	breaking changes file schemas & :ac:`CLI` :ac:`API`. Additionally, anything after
+	tagged, the maker reserves the right to obliterate & amend patches.
+
+Quickstart
+===============================================================================
+
+Set up
+-------------------------------------------------------------------------------
+
+.. code:: console
+
+	$ nixtamal set-up
+	Creating Nixtamal directory @ ./nix/tamal
+	Writing new Nixtamal EditorConfig @ ./nix/tamal/.editorconfig …
+	Fetching latest value for 「nixpkgs」 …
+	Prefetching input 「nixpkgs」 … (this may take a while)
+	Prefetched 「nixpkgs」.
+	Making manifest file @ version:0.0.1
+	Writing manifest @ manifest.kdl …
+	Manifest written.
+	Writing lockfile @ lock.json …
+	Lockfile written.
+	Writing lock loader @ default.nix …
+	Lock loader written.
+
+	$ tree nix/tamal
+	nix/tamal
+	├── default.nix
+	├── lock.json
+	└── manifest.kdl
+
+	1 directory, 3 files
+
+
+Use with a Nix project — such as in a ``release.nix``
+-------------------------------------------------------------------------------
+
+.. code:: nix
+
+	let
+		inputs = import nix/tamal { };
+		pkgs = import inputs.nixpkgs { };
+	in
+	{
+		inherit (pkgs) hello;
+	}
+
+Add a new input to pin
+-------------------------------------------------------------------------------
+
+See: `<docs/manifest.rst>`_
+
+.. code:: console
+
+	$ nixtamal tweak
+
+Opens text editor. & After editing …
+
+Lock or refresh you inputs
+-------------------------------------------------------------------------------
+
+.. code:: console
+
+	$ nixtamal lock
+	$ nixtamal refresh
+
+What next?
+-------------------------------------------------------------------------------
+
+As they say: read the manpages
+
+.. code:: console
+
+	$ man nixtamal
+	$ man nixtamal-manifest
+
+
+Building
+===============================================================================
+
+.. code:: console
+
+	$ nix-shell -p darcs \
+		--run "darcs clone 'https://darcs.toastal.in.th/nixtamal/trunk/' nixtamal"
+	$ cd nixtamal
+	$ nix-build
+
 
 License
 ===============================================================================
diff --git a/lib/lock_loader.ml b/lib/lock_loader.ml
index a313d55..b199342 100644
--- a/lib/lock_loader.ml
+++ b/lib/lock_loader.ml
@@ -386,7 +386,7 @@ let pp ~version (ppf : Format.formatter) =
 	pf ppf "@.@.";
 	pp_body ~version ppf ()
 
-let write ?(version = "0.0.1") () =
+let write ?(version = "0.1.0") () =
 	let working_dir = Working_directory.get () in
 	let filepath = Eio.Path.(working_dir / filename) in
 	let () =
diff --git a/lib/lockfile.ml b/lib/lockfile.ml
index 658170e..af496bf 100644
--- a/lib/lockfile.ml
+++ b/lib/lockfile.ml
@@ -417,7 +417,7 @@ let jsont : t Jsont.t =
 	|> Object.mem "i" (NameMap.jsont ~kind: "Input" Input'.jsont) ~enc: (fun i -> i.inputs)
 	|> Object.finish
 
-let make ?(version = "0.0.1") () =
+let make ?(version = "0.1.0") () =
 	Logs.info (fun m -> m "Making lockfile @@ version:%s …" version);
 	let inputs =
 		Input_foreman.to_lockfile (fun input ->
diff --git a/lib/manifest.ml b/lib/manifest.ml
index 59a8e2c..2583e74 100644
--- a/lib/manifest.ml
+++ b/lib/manifest.ml
@@ -683,7 +683,7 @@ let read () =
 	let () = manifest := Some kdl in
 	Ok kdl
 
-let make ?(version = "0.0.1") () =
+let make ?(version = "0.1.0") () =
 	Logs.app (fun m -> m "Making manifest file @@ version:%s" version);
 	let open Kdl in
 	let doc = [
-- 
cgit v1.2.3